home *** CD-ROM | disk | FTP | other *** search
/ User's Choice Windows CD / User's Choice Windows CD (CMS Software)(1993).iso / win_u_z / wedl121.zip / WEDL.DOC < prev    next >
Text File  |  1991-12-09  |  140KB  |  3,824 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.                 +----------------------------------------------+
  14.                 |                                              |
  15.                 |      W          W  EEEEE  DDDD    LL         |
  16.                 |      WW        WW  EE     DD  D   LL         |
  17.                 |       WW  WW  WW   EEEE   DD   D  LL         |
  18.                 |        WW WW WW    EE     DD  D   LL         |
  19.                 |         WW  WW     EEEEE  DDDD    LLLLLL     |
  20.                 |                                              |
  21.                 |                                              |
  22.                 |        Windows Enhanced Dialog Library       |
  23.                 |                                              |
  24.                 |                                              |
  25.                 |             Programmer's Manual              |
  26.                 |                                              |
  27.                 |                                              |
  28.                 |      Copyright (c) 1991, Mike Smedley        |
  29.                 |                                              |
  30.                 |             All Rights Reserved              |
  31.                 |                                              |
  32.                 |                                              |
  33.                 |               Version 1.21                   |
  34.                 |                                              |
  35.                 |             December 9, 1991                 |
  36.                 |                                              |
  37.                 +----------------------------------------------+
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.                                       1    
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.                                 SOFTWARE LICENSE
  67.  
  68.     This evaluation version of WEDL may be distributed, only in its
  69.     entirety, for others to evaluate.  None of the evaluation files may be
  70.     modified or deleted.  The evaluation version of the WEDL dynamic-link
  71.     library (file name WEDL-E.DLL) cannot be distributed with applications
  72.     built that use it.  This requires registration of the software.
  73.  
  74.     Software distribution companies that distribute user-supported software
  75.     may distribute this evaluation version of WEDL and charge a disk copying
  76.     fee not to exceed $10.00 in U.S. currency.
  77.  
  78.  
  79.  
  80.  
  81.  
  82.  
  83.                                    DISCLAIMER
  84.  
  85.     The author of this software package, Mike Smedley, has used his best
  86.     efforts in producing this software and documentation.  These efforts
  87.     include the research, development, and testing of the software, and
  88.     production of the documentation.
  89.  
  90.     The author makes no warranty of any kind, expressed or implied, with
  91.     regards to the software or the documentation.  The author shall not be
  92.     liable in any event for incidental or consequential damages in
  93.     connection with, or arising out of, the furnishing, performance, or use
  94.     of this software package.
  95.  
  96.     All pricing subject to change without notice.
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.                                       2    
  113.  
  114.  
  115.                                TABLE OF CONTENTS
  116.  
  117.  
  118.     Acknowledgements.....................................................6
  119.     Introduction.........................................................7
  120.     Welcome to WEDL!.....................................................8
  121.     WEDL Features........................................................8
  122.     System Requirements..................................................10
  123.     Archive Contents.....................................................10
  124.     Registration Information.............................................11
  125.     WEDL Registration Form...............................................12
  126.     Contacting the Author................................................13
  127.     Programming Guide....................................................14
  128.     Terminology..........................................................15
  129.     Naming Conventions...................................................15
  130.     How WEDL Fields Work.................................................15
  131.     Creating the Dialog Box..............................................16
  132.     Layout of the Dialog Procedure.......................................16
  133.     Defining the Form....................................................17
  134.     Defining Fields......................................................18
  135.     Defining Buttons.....................................................18
  136.     Defining Generic Controls............................................19
  137.     Defining Status Messages.............................................20
  138.     Writing Field Validation Functions...................................20
  139.     Writing Error Handlers...............................................21
  140.     Defining Context-Sensitive Help......................................21
  141.     Compiling and Linking................................................22
  142.     Executing the Program................................................22
  143.     Common Programming Errors............................................22
  144.     Function Reference...................................................25
  145.     button_define........................................................26
  146.     button_get_check.....................................................27
  147.     button_get_from_ctrl_id..............................................27
  148.     button_get_from_group................................................28
  149.     button_get_from_hwnd.................................................28
  150.     button_has_changed...................................................28
  151.     button_lock..........................................................29
  152.     button_set_check.....................................................29
  153.     button_unlock........................................................30
  154.     char_is_printable....................................................30
  155.     char_to_lower........................................................30
  156.     char_to_upper........................................................31
  157.     dproc_enter_error....................................................31
  158.     dproc_enter_idcancel.................................................31
  159.     dproc_enter_idok.....................................................31
  160.     dproc_enter_wm_command...............................................32
  161.     dproc_exit_error.....................................................32
  162.     field_data_to_log....................................................33
  163.     field_define.........................................................33
  164.     field_disable_feature................................................38
  165.  
  166.  
  167.  
  168.                                       3    
  169.     field_enable_feature.................................................38
  170.     field_get_character..................................................39
  171.     field_get_decimal_pos................................................39
  172.     field_get_from_ctrl_id...............................................39
  173.     field_get_from_hwnd..................................................40
  174.     field_get_pos_info...................................................40
  175.     field_get_position...................................................41
  176.     field_get_text.......................................................41
  177.     field_has_changed....................................................41
  178.     field_insert_decimal.................................................42
  179.     field_lock...........................................................42
  180.     field_log_to_data....................................................43
  181.     field_log_to_phys....................................................43
  182.     field_phys_to_log....................................................44
  183.     field_set_text.......................................................44
  184.     field_unlock.........................................................44
  185.     form_begin...........................................................45
  186.     form_end.............................................................45
  187.     form_get_active......................................................45
  188.     form_get_from_hdlg...................................................46
  189.     form_has_changed.....................................................46
  190.     form_in_error_cond...................................................46
  191.     form_is_cancelled....................................................47
  192.     form_lock............................................................47
  193.     form_process.........................................................48
  194.     form_set_help........................................................48
  195.     form_terminate.......................................................49
  196.     form_unlock..........................................................49
  197.     form_validate........................................................49
  198.     genctrl_define.......................................................50
  199.     statmsg_define.......................................................50
  200.     str_delete_char......................................................51
  201.     str_insert_char......................................................52
  202.     str_is_blank.........................................................52
  203.     str_is_value_zero....................................................52
  204.     str_trim_spaces......................................................53
  205.     Data Type Reference..................................................54
  206.     BUTTON...............................................................55
  207.     FIELD................................................................56
  208.     FIELD_POS............................................................57
  209.     FORM.................................................................58
  210.     HBUTTON..............................................................61
  211.     HFIELD...............................................................61
  212.     HFORM................................................................61
  213.     HGENCTRL.............................................................61
  214.     LPBUTTON.............................................................61
  215.     LPFIELD..............................................................61
  216.     LPFIELD_POS..........................................................62
  217.     LPFORM...............................................................62
  218.     PBUTTON..............................................................62
  219.     PFIELD...............................................................62
  220.     PFIELD_POS...........................................................62
  221.     PFORM................................................................62
  222.  
  223.  
  224.                                       4    
  225.     PROC_ARRAY_INFO......................................................62
  226.     Appendix A:  Picture String Characters...............................64
  227.     Appendix B:  Field Editing Keys......................................66
  228.     Appendix C:  Glossary................................................68
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.                                       5    
  281.  
  282.  
  283.  
  284.     Acknowledgements
  285.  
  286.     BIX is a registered trademark of McGraw-Hill, Inc.
  287.     Borland is a registered trademark of Borland International.
  288.     CompuServe is a registered trademark of CompuServe, Inc.
  289.     IBM is a registered trademark of International Business Machines.
  290.     Microsoft is a registered trademark of the Microsoft Corporation.
  291.     MS-DOS is a registered trademark of the Microsoft Corporation.
  292.     Windows is a trademark of the Microsoft Corporation.
  293.  
  294.     This manual was written using Microsoft Word for Windows.
  295.     This manual was printed on a Hewlett-Packard LaserJet IIP.
  296.     The software was written using SemWare's QEdit text editor.
  297.     The resources for the demo program were created using Borland's Resource
  298.     Workshop.
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.                                       6    
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.                                 Introduction
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.                                       7    
  393.  
  394.  
  395.     Welcome to WEDL!
  396.  
  397.     Welcome to WEDL, the Windows Enhanced Dialog Library.  WEDL (pronounced
  398.     "weddle") is a collection of C functions for Microsoft Windows
  399.     programmers designed to make dialog box data entry much easier for both
  400.     the programmer and the user.
  401.  
  402.  
  403.     WEDL Features
  404.  
  405.     Enhanced Edit Fields
  406.  
  407.         Formatted Data Entry
  408.  
  409.             Picture strings are assigned to fields which describe the
  410.             allowable characters for each field position and specify the
  411.             position of formatting characters which aid the user in
  412.             correctly entering data.  For example, a telephone number field
  413.             could visually look like "(___)___-____" instead of just
  414.             "__________".  The user is not able to move the cursor to, or
  415.             edit, the embedded formatting characters.
  416.  
  417.         Field Validation
  418.  
  419.             Extensive field validation is provided via WEDL's own internal
  420.             validations and optionally through programmer-written validation
  421.             functions.  Validation is provided internally by picture strings
  422.             which describe the allowable characters for each field position,
  423.             and optional field validations such as Field Cannot Be Blank,
  424.             Field Cannot Be Zero, and Field Cannot Be Edited.  In addition,
  425.             you can write validation functions to perform any other needed
  426.             validations.  The user is not able to leave the field or select
  427.             "OK" until the field passes validation.
  428.  
  429.         Automatic Reading and Writing of Variables
  430.  
  431.             WEDL can automatically read and write your program's variables,
  432.             placing their contents into the fields for updating, then
  433.             storing the contents of the fields back to the variables upon
  434.             completion of the form.  Data type conversion is performed
  435.             on-the-fly.  This saves you from having to set and get the
  436.             contents of the fields and convert between data types.  The data
  437.             types supported by WEDL fields include character string, int,
  438.             unsigned, long, unsigned long, and double.
  439.  
  440.         Numeric Data Entry
  441.  
  442.             Numeric data entry is fully supported by WEDL.  There is a
  443.             standard numeric field which supports left-to-right digit input
  444.             and a decimal point. In addition, there is a calculator-style
  445.             numeric field which supports right-to-left digit input, a
  446.  
  447.  
  448.                                       8    
  449.             decimal point, and optional commas which appear only when a
  450.             digit precedes them (eg. the user would see "1,000.00" instead
  451.             of "1000.00").
  452.  
  453.         Overtype Mode
  454.  
  455.             WEDL fields provide an overtype mode in addition to the insert
  456.             mode Windows' edit fields provide.
  457.  
  458.         Case Conversion
  459.  
  460.             WEDL can automatically convert letters entered into a field to
  461.             uppercase or lowercase.  Also, there is a mixed-case option
  462.             which converts characters to uppercase or lowercase depending on
  463.             the previous character (eg. "Mixed Case").  Foreign alphabetic
  464.             characters are supported.
  465.  
  466.         Enhanced Editing Keys
  467.  
  468.             In addition to the editing keys available in Windows' edit
  469.             fields, WEDL provides a variety of new editing keys.  See
  470.             Appendix B for a list of editing keys.
  471.  
  472.     Enhanced Radio Buttons and Check Boxes
  473.  
  474.         Automatic Reading and Writing of Variables
  475.  
  476.             WEDL can automatically read and write your program's variables,
  477.             setting radio buttons and check boxes according to the
  478.             variables' values, then when the form is finished, the variables
  479.             are updated to specified values indicating whether the buttons
  480.             or check boxes are checked or not.  For a group of radio buttons
  481.             within a group box, a variable can automatically be set to a
  482.             value indicating which button in the group was checked.
  483.  
  484.     Enhanced Combo Boxes
  485.  
  486.         The edit fields in combo boxes have the same features as standard
  487.         edit fields, in addition to the ability to interact with the combo
  488.         box's list box.
  489.  
  490.     Context-Sensitive Help
  491.  
  492.         Context-sensitive help can easily be applied to individual fields,
  493.         radio buttons, check boxes, combo boxes, or any other control within
  494.         a dialog box.  When the user presses the F1 key, the Windows Help
  495.         application will be run and help information for the current control
  496.         will be displayed.
  497.  
  498.     Dynamic-Link Library
  499.  
  500.         WEDL's functions are contained in a Windows dynamic-link library.
  501.         The .DLL library format has many advantages over the normal .LIB
  502.  
  503.  
  504.                                       9    
  505.         format.  These include:
  506.  
  507.             The dynamic-link library will be loaded only once into memory,
  508.             no matter how many running applications use it.
  509.  
  510.             There is no need for multiple memory model versions of the
  511.             library.  No matter which memory model your program is written
  512.             in, it still uses the same dynamic-link library.
  513.  
  514.             The dynamic-link library is not compiler-specific.  Any C or C++
  515.             compiler that supports the creation of Windows applications will
  516.             be able to use WEDL.  Other language compilers that can produce
  517.             Windows applications may also be compatible with WEDL.
  518.  
  519.     Compatibility
  520.  
  521.         Since WEDL's functions are contained in a dynamic-link library, any
  522.         C or C++ compiler that supports the creation of Windows applications
  523.         will be able to use WEDL.
  524.  
  525.         WEDL does not replace Windows' dialog controls; it extends their
  526.         capabilities by subclassing them. Therefore WEDL is compatible with
  527.         all resource editors and CASE products that produce resource files.
  528.  
  529.         WEDL is compatible with foreign languages supported by Windows'
  530.         language driver.
  531.  
  532.  
  533.     System Requirements
  534.  
  535.     Microsoft Windows version 3.0 or greater (real, standard, or enhanced
  536.     mode). MS-DOS version 3.1 or greater.
  537.  
  538.     Microsoft Windows Software Development Kit or compatible tools.
  539.  
  540.     To use the WEDL library:
  541.         Any C or C++ compiler capable of producing Windows programs.  Other
  542.         language compilers may or may not be compatible.
  543.  
  544.     To rebuild the WEDL library:
  545.         Microsoft C 6.0 and Borland C++ 2.0 have been successfully tested.
  546.         Other C or C++ compilers may work as well.
  547.  
  548.  
  549.     Archive Contents
  550.  
  551.     The contents of the WEDL___.ZIP archive file are as follows:
  552.  
  553.     File Name       Description
  554.     ---------       -----------
  555.     DEMO.DEF        Demonstration program module definition file.
  556.     DEMO.EXE        Demonstration program executable file.
  557.     DEMO.H          Demonstration program header file.
  558.  
  559.  
  560.                                       10   
  561.     DEMO.ICO        Application icon for the demonstration program.
  562.     DEMO.MAK        Demonstration program make file.
  563.     DEMO.RC         Demonstration program resource source file.
  564.     DEMO?.C         Demonstration program source code files.
  565.     DEMOHELP.H      Header file containing demonstration program help
  566.                     definitions.
  567.     DEMOHELP.HLP    Demonstration program help file.
  568.     DEMOHELP.HPJ    Project file for the demonstration program's help file.
  569.     DEMOHELP.RTF    Source text for demonstration program's help file.
  570.     READ.ME         Contains last-minute updates and other important
  571.                     information.
  572.     REGISTER.DOC    Information about registering WEDL.
  573.     WEDL.DOC        WEDL documentation file.  (You are reading it now.)
  574.     WEDL-E.DLL      WEDL dynamic-link library.
  575.     WEDL.H          WEDL header file.
  576.     WEDL-E.LIB      WEDL import library.
  577.  
  578.  
  579.     Registration Information
  580.  
  581.     WEDL is a user-supported software product.  This means you are free to
  582.     try the software long enough to evaluate it and see if it meets your
  583.     needs. After a reasonable evaluation period, you are expected to either
  584.     register the software or cease using it.  Registering the software gives
  585.     you many benefits including:
  586.  
  587.         --  The full library source code.
  588.  
  589.         --  A high-quality printed manual.
  590.  
  591.         --  Royalty-free distribution of the WEDL.DLL library.  The
  592.             evaluation version, WEDL-E.DLL, cannot be distributed.
  593.  
  594.         --  Unlimited technical support via E-mail or postal mail.
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.                                       11   
  612.  
  613.                               WEDL REGISTRATION FORM
  614.  
  615.  
  616.     NAME:___________________________________________________________________
  617.  
  618.  
  619.     COMPANY:________________________________________________________________
  620.  
  621.  
  622.     ADDRESS:________________________________________________________________
  623.  
  624.  
  625.     ________________________________________________________________________
  626.  
  627.  
  628.     CITY, STATE:____________________________________________________________
  629.  
  630.  
  631.     ZIP CODE: ____________________________  COUNTRY:________________________
  632.  
  633.  
  634.     TELEPHONE NUMBER:___________________  DISK SIZE:   5.25"    /    3.5"
  635.  
  636.  
  637.     WHERE DID YOU RECEIVE WEDL?_____________________________________________
  638.  
  639.  
  640.     WEDL Registration @ $55.00 per copy                        _____________
  641.  
  642.     Shipping and Handling
  643.     (U.S.A. and Canada = $5.00,  Overseas = $10.00) per copy   _____________
  644.  
  645.  
  646.     Florida Residents, Add 7% State Sales Tax ($4.20) per copy _____________
  647.  
  648.  
  649.     Total Amount Enclosed:                                     _____________
  650.  
  651.  
  652.     Payment must be with a check or money order payable in U.S. dollars and
  653.     drawn on a U.S. bank.  Make checks payable to Mike Smedley.
  654.  
  655.     Purchase orders are accepted from Fortune 500, government, or
  656.     educational institutions ONLY for orders of 3 copies or more.
  657.  
  658.     To register WEDL, send the above information and payment to:
  659.  
  660.             Mike Smedley
  661.             P.O. Box 17325
  662.             Jacksonville, FL 32245-7325
  663.  
  664.  
  665.  
  666.  
  667.                                       12   
  668.  
  669.     Contacting the Author
  670.  
  671.     The author, Mike Smedley, can be contacted via one of the following
  672.     methods:
  673.  
  674.         Electronic Mail:
  675.             BIX:            m.smedley
  676.             CompuServe:     71331,2244
  677.  
  678.         Postal Mail:
  679.             Mike Smedley
  680.             P.O. Box 17325
  681.             Jacksonville, FL  32245-7325
  682.  
  683.     Electronic mail is the fastest and most reliable way to get technical
  684.     support.  If enough interest is expressed in WEDL, a bulletin board
  685.     system (BBS) may be established to provide even greater technical
  686.     support.
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.                                Programming Guide
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.  
  735.  
  736.  
  737.  
  738.  
  739.  
  740.  
  741.  
  742.                                       14   
  743.  
  744.  
  745.     Terminology
  746.  
  747.     There are several terms that are used throughout this manual that are
  748.     important to understand.  Consult the Glossary in the back of this
  749.     manual for the definition of any terms you do not understand.
  750.  
  751.  
  752.     Naming Conventions
  753.  
  754.     Function Naming
  755.  
  756.         WEDL's functions are named in an object-oriented manner.  The first
  757.         part of the function name is the prefix which identifies the type of
  758.         object the function operates on.  The second part of the function
  759.         name identifies the action to perform on the object.  The following
  760.         is a list of prefixes used by WEDL functions:
  761.  
  762.         Prefix          Meaning
  763.         ------          -------
  764.         button_         Function operates on a button.
  765.         char_           Function operates on a character.
  766.         dproc_          Function operates on the dialog procedure.
  767.         field_          Function operates on a field.
  768.         form_           Function operates on a form.
  769.         genctrl_        Function operates on a generic control.
  770.         statmsg_        Function operates on a key status message.
  771.         str_            Function operates on a character string.
  772.  
  773.     Data Type and Variable Naming
  774.  
  775.         Data type and variable naming in WEDL is fairly consistent.  The
  776.         prefix 'h' is used for data types and variables corresponding to
  777.         handles.  The prefix 'p' is used for data types and variables
  778.         corresponding to pointers (not specifying near or far).  The prefix
  779.         'lp' is used for data types and variables corresponding to far
  780.         pointers.
  781.  
  782.  
  783.     How WEDL Fields Work
  784.  
  785.     WEDL fields may have embedded formatting characters in them in order to
  786.     assist the user in correctly inputting the required data.  For example,
  787.     the '(', ')', and '-' characters in a phone number field are considered
  788.     formatting characters.  Also there are special formatting characters
  789.     such as the commas and decimal point in numeric fields.  The user is not
  790.     able to move the cursor to, or edit, the formatting characters.
  791.     Formatting characters are not copied to the destination by default.
  792.  
  793.     Fields that contain embedded formatting characters are considered to be
  794.     in physical field format.  If you were to call the GetDlgItemText
  795.     function, you would get the field's physical contents.  Fields that do
  796.  
  797.  
  798.                                       15   
  799.     not contain embedded formatting characters are considered to be in
  800.     logical field format.
  801.  
  802.     When defining a field, the data type of the associated variable is
  803.     converted to a character string in physical field format and this string
  804.     is used to set the contents of the field.  When the user selects "OK",
  805.     the field's contents are converted back to the data types of their
  806.     variables and stored.
  807.  
  808.  
  809.     Creating the Dialog Box
  810.  
  811.     When creating a dialog box to be used with WEDL, very few special
  812.     considerations are needed.  You use your dialog box resource editor as
  813.     normal.  For edit controls to be defined as WEDL fields, you should
  814.     specify the WS_TABSTOP, WS_BORDER, WS_CHILD, ES_LEFT, and ES_AUTOHSCROLL
  815.     styles. For edit controls that belong to a combo box, use
  816.     CBS_AUTOHSCROLL instead of ES_AUTOHSCROLL.
  817.  
  818.     For radio buttons and check boxes, you should specify the
  819.     BS_AUTORADIOBUTTON or BS_AUTOCHECKBOX styles respectively.  If the check
  820.     box is a 3-state check box, use BS_AUTO3STATE.
  821.  
  822.     If you desire to have an automatically-updated Insert, CapsLock, or
  823.     NumLock key status message in your dialog box, place a static text
  824.     control for each message where you want the message to appear in the
  825.     dialog box.  The static text control must be wide enough to display the
  826.     entire status message.
  827.  
  828.     When assigning control IDs to the controls in the dialog box, avoid
  829.     using values 27700 - 27799.  These values are reserved by WEDL.
  830.  
  831.  
  832.     Layout of the Dialog Procedure
  833.  
  834.     The dialog procedure is where all definition and processing of the form
  835.     occur.  The layout of the dialog procedure is as follows:
  836.  
  837.     int FAR PASCAL DialogProc( HWND hDlg, unsigned message, WORD wParam,
  838.                                LONG lParam )
  839.     {
  840.         static HFORM hform = NULL;      /* must be static or global! */
  841.  
  842.         switch( message ) {
  843.  
  844.             case WM_INITDIALOG:
  845.                 /* Do not call any Windows functions that generate */
  846.                 /* WM_COMMAND messages before defining the form!   */
  847.                 hform = form_begin( hDlg );
  848.                 /* Call field_define() for each field to be defined. */
  849.                 /* Call button_define() for each button to be defined. */
  850.                 /* Call genctrl_define() for each generic control. */
  851.                 /* Call statmsg_define() for each status message. */
  852.  
  853.  
  854.                                       16   
  855.                 form_end( hform );
  856.                 /* Perform any other WM_INITDIALOG processing. */
  857.                 return( TRUE );
  858.  
  859.             case WM_COMMAND:
  860.                 dproc_enter_wm_command( hform, wParam, lParam );
  861.                 switch( wParam ) {
  862.  
  863.                     /* Add a case statement for each error value */
  864.                     /* given in your calls to field_define().    */
  865.  
  866.                     case MY_ERROR_VALUE:    /* defined by the programmer */
  867.                         dproc_enter_error( hform );
  868.                         /* display error message, etc. */
  869.                         dproc_exit_error( hform, lParam );
  870.                         return( TRUE );
  871.  
  872.                     case IDOK:
  873.                         dproc_enter_idok( hform );
  874.                         if( !form_in_error_cond( hform ) ) {
  875.                             if( form_validate( hform ) != NULL ) break;
  876.                                 form_process( hform );
  877.                                 EndDialog( hDlg, TRUE );
  878.                                 form_terminate( hform );
  879.                                 /* Perform other IDOK processing. */
  880.                         }
  881.                         return( TRUE );
  882.  
  883.                     case IDCANCEL:
  884.                         dproc_enter_idcancel( hform );
  885.                         EndDialog( hDlg, TRUE );
  886.                         form_terminate( hform );
  887.                         /* Perform other IDCANCEL processing. */
  888.                         return( TRUE );
  889.                 }
  890.                 break;
  891.         }
  892.         return( FALSE );
  893.     }
  894.  
  895.  
  896.     Defining the Form
  897.  
  898.     The definition of a form is performed during WM_INITDIALOG message
  899.     processing in the dialog procedure.  The form_begin and form_end
  900.     functions are required for form definition.  The functions used to
  901.     define controls within the form are field_define, button_define,
  902.     genctrl_define and statmsg_define. These functions define fields,
  903.     buttons, generic controls, and status messages respectively.  The calls
  904.     to these functions must be made between form_begin and form_end.
  905.  
  906.     It is recommended that form_begin be called immediately upon entry into
  907.     WM_INITDIALOG.  If you call any Windows function which generate
  908.  
  909.  
  910.                                       17   
  911.     WM_COMMAND messages before the form is defined, the form handle returned
  912.     by form_begin will not be valid and any WM_COMMAND message processing
  913.     which relies on a valid form handle will fail.
  914.  
  915.     If you are planning on adding context-sensitive help to individual
  916.     controls, you will need to call the form_set_help function somewhere
  917.     after form_begin.  The form_set_help function sets the Windows Help file
  918.     name that will be used for context-sensitive help.
  919.  
  920.  
  921.     Defining Fields
  922.  
  923.     A field is an edit control within your dialog box and is usually of
  924.     class "edit".  To define a field, you must call the field_define
  925.     function for a given edit control.  Not all edit controls have to be
  926.     defined, but if you want them to have WEDL field capabilities, you
  927.     should define them.  The purpose of defining a field is to:
  928.  
  929.         1.  Assign a picture string to the field.  The picture string
  930.         defines the size of the field, the allowable characters for each
  931.         field position, and the placement of formatting characters in the
  932.         field.  See Appendix A for a list of characters that can be used in
  933.         picture strings.
  934.  
  935.         2.  Optionally assign a variable to the field.  The variable can be
  936.         initialized or updated by the field.
  937.  
  938.         3.  Optionally specify various behavioral features of the field.
  939.         Such features include numeric formatting, case conversion, space
  940.         padding, and whether the field belongs to a combo box. See the
  941.         description of the field_define function for a list of features that
  942.         can be specified.
  943.  
  944.         4.  Optionally assign a validation function to the field.  The
  945.         validation function is written by you, the programmer, to validate
  946.         the contents of the field.  See the section on writing field
  947.         validation functions below for more information.
  948.  
  949.         5.  Optionally assign a Windows Help context to the field.  If the
  950.         user presses F1 in the field, a help screen will be displayed with
  951.         information on that particular field.  See the section on defining
  952.         context-sensitive help for more information.
  953.  
  954.     The following is an example of a call to field_define:
  955.  
  956.         field_define( hform, ID_ACCTNO, &acct_no, DT_INTEGER, "###",
  957.                       FDF_NUMERIC | FDF_NOTZERO, pcheck_acct_num,
  958.                       BAD_ACCTNO, HELPID_ACCTNO );
  959.  
  960.  
  961.     Defining Buttons
  962.  
  963.     A button is a control within your dialog box that typically has an on or
  964.  
  965.  
  966.                                       18   
  967.     off state.  The control is usually of class "button" and can be a radio
  968.     button, check box, or compatible button.  To define a button, you must
  969.     call the button_define function for a given button control.  Not all
  970.     button controls have to be defined, but if you want them to have WEDL
  971.     button capabilities, you should define them.  The purpose of defining a
  972.     button is to:
  973.  
  974.         1.  Optionally assign a variable to the button.  The variable can be
  975.         set to a value indicating whether the button has been checked or not
  976.         checked.  The variable can also be set to a value indicating which
  977.         button in a group of buttons was checked.
  978.  
  979.         2.  Optionally initialize the state of the button.  The button can
  980.         be initialized on, off, grayed (disabled), or can be set according
  981.         to the value of the variable assigned to the button.
  982.  
  983.         3.  Optionally assign a Windows Help context to the button.  If the
  984.         user presses F1 while on the button, a help screen will be displayed
  985.         with information on that particular button.  See the section on
  986.         defining context-sensitive help for more information.
  987.  
  988.     Do not use button_define to define a push button.  Since a push button
  989.     only has an instantaneous "on" state, assigning a variable to the button
  990.     would be useless.  Use the genctrl_define function for defining push
  991.     buttons.  The "OK" and "Cancel" buttons are defined by default because
  992.     WEDL needs to maintain them.
  993.  
  994.     The following is an example of a call to button_define where the button
  995.     is not part of a group:
  996.  
  997.         button_define( hform, ID_SAVECHANGES, &bSaveChanges, 0, TRUE, FALSE,
  998.                        BS_OFF, HELPID_SAVECHANGES );
  999.  
  1000.     The following calls to button_define demonstrate the definition of a
  1001.     group of 3 related buttons:
  1002.  
  1003.         button_define( hform, ID_XMODEM, &protocol, 1, ID_XMODEM, 0,
  1004.                        BS_USEDATA, HELPID_XMODEM );
  1005.         button_define( hform, ID_YMODEM, &protocol, 1, ID_YMODEM, 0,
  1006.                        BS_USEDATA, HELPID_YMODEM );
  1007.         button_define( hform, ID_ZMODEM, &protocol, 1, ID_ZMODEM, 0,
  1008.                        BS_USEDATA, HELPID_ZMODEM );
  1009.  
  1010.  
  1011.     Defining Generic Controls
  1012.  
  1013.     A generic control can be any control within your dialog box.  It is
  1014.     usually a list box, push button, or custom control.  To define a generic
  1015.     control, you must call the genctrl_define function for a given dialog
  1016.     box control.  The only reasons for defining a generic control are to
  1017.     assign context-sensitive help to it, and to make sure that status
  1018.     messages get updated if the Insert, CapsLock, or NumLock keys are
  1019.     pressed while the control has input focus.
  1020.  
  1021.  
  1022.                                       19   
  1023.  
  1024.     The following is an example of a call to genctrl_define:
  1025.  
  1026.         genctrl_define( hform, ID_LISTBOX, HELPID_LISTBOX );
  1027.  
  1028.  
  1029.     Defining Status Messages
  1030.  
  1031.     In many circumstances, it is desirable to have a status message
  1032.     indicating whether the Insert, CapsLock, or NumLock key is toggled on or
  1033.     off.  WEDL provides a simple method for creating these automatically-
  1034.     updated key status messages.  All you have to do is define a static text
  1035.     control (class "static") in your dialog box to be used for the
  1036.     displaying of the status message.  Then call the statmsg_define function
  1037.     to link the key to the status message.
  1038.  
  1039.     The only drawbacks to these types of status messages is they cannot be
  1040.     updated while the input focus is set to a control not defined by WEDL.
  1041.     When the user moves to a control that has been defined by WEDL, the
  1042.     status message will be updated.
  1043.  
  1044.  
  1045.     Writing Field Validation Functions
  1046.  
  1047.     A field validation function is a function written by you, the
  1048.     programmer, to validate the information in a field. The validation
  1049.     function is called both when the user tries to leave the field and when
  1050.     the user selects "OK". The exception to this rule is when the field has
  1051.     the FDF_VAFFRM feature specified, in which case the validation function
  1052.     is called only when the user selects "OK".  A validation function is
  1053.     assigned to a field by the field_define function.  The validation
  1054.     function must be declared in this form:
  1055.  
  1056.         int FAR PASCAL ValidationFunc( LPSTR pbuf );
  1057.  
  1058.     Since the validation function is a callback function, it must be
  1059.     declared FAR and have an entry in the EXPORTS section of your
  1060.     application's module definition file.
  1061.  
  1062.     The validation function is passed a pointer to a temporary buffer
  1063.     containing a character string in logical field format.  You use this
  1064.     character string to validate the field.  If you need to convert the
  1065.     value to a numeric data type, you can use the field_log_to_data function
  1066.     to do so.  You may also use the atoi, atol, or field_insert_dec/atof
  1067.     functions for converting the string to a numeric data type.
  1068.  
  1069.     When you are done validating the field's contents, you return either
  1070.     zero if the field contains no errors or the position of the error in the
  1071.     field + 1.
  1072.  
  1073.     The following is an example of a validation function that checks an
  1074.     account number and makes sure it is within 100 and 400:
  1075.  
  1076.  
  1077.  
  1078.                                       20   
  1079.         int FAR PASCAL check_acct_num( LPSTR pbuf )
  1080.         {
  1081.             int acctno;
  1082.  
  1083.             acctno = atoi( pbuf );
  1084.             if( acctno < 100 || acctno > 400 ) return( 1 );
  1085.             return( 0 );
  1086.         }
  1087.  
  1088.     Use the validation function only for validating the field.  If you call
  1089.     Windows functions which generate messages, you chance crashing your
  1090.     program.  Modifying the contents of the temporary buffer will not change
  1091.     the contents of the field and is not recommended.
  1092.  
  1093.  
  1094.     Writing Error Handlers
  1095.  
  1096.     For every validation function, there is a corresponding error handler.
  1097.     The error handler is a piece of code that is responsible for displaying
  1098.     an error message, sounding a an audible beep, or any other actions you
  1099.     want to take in the event of an error.  WEDL takes care of repositioning
  1100.     the cursor to the position of the error in the field.
  1101.  
  1102.     The error handler is written in the dialog procedure.  The errval
  1103.     parameter you specified in the call to the field_define function is
  1104.     passed in the wParam parameter of the WM_COMMAND message.  You must call
  1105.     the dproc_enter_error function immediately upon entry into the error
  1106.     handler and dproc_exit_error just before leaving the error handler.  The
  1107.     error handler returns TRUE indicating the dialog procedure handled the
  1108.     message.
  1109.  
  1110.     The following is an example error handler:
  1111.  
  1112.         case BAD_ACCTNO:
  1113.             dproc_enter_error( hform );
  1114.             MessageBeep( 0 );
  1115.             MessageBox( hDlg, "Account number is invalid!", NULL, MB_OK );
  1116.             dproc_exit_error( hform, lParam );
  1117.             return( TRUE );
  1118.  
  1119.  
  1120.     Defining Context-Sensitive Help
  1121.  
  1122.     Context-sensitive help can be applied to controls defined by WEDL.  WEDL
  1123.     uses the standard Windows Help application and F1 key in its
  1124.     implementation.  First you must call the form_set_help function to let
  1125.     WEDL know you'll be using context-sensitive help and to specify the name
  1126.     of the Windows Help file that will be used.  You should call this
  1127.     function somewhere in the dialog procedure's WM_INITDIALOG message
  1128.     processing after form_begin has been called.
  1129.  
  1130.     In the field_define, button_define, and genctrl_define function calls,
  1131.     one of the parameters, help_context, is used to specify the context ID
  1132.  
  1133.  
  1134.                                       21   
  1135.     of the Windows Help topic associated with the control.  If the user
  1136.     presses F1 while in a control with a nonzero help_context, the Windows
  1137.     Help application will be executed.  Then Windows Help will automatically
  1138.     load the help file specified in the form_set_help function and display
  1139.     the topic for the control's help_context.
  1140.  
  1141.     To create a Windows Help file, you'll need a word processing program
  1142.     capable of producing Rich Text Format (.RTF) files and the help compiler
  1143.     included in the Microsoft Windows Software Development Kit. There is
  1144.     plenty of information on this in the Windows SDK documentation, so there
  1145.     is no need to cover this here.
  1146.  
  1147.  
  1148.     Compiling and Linking
  1149.  
  1150.     To create programs that use WEDL, you need the WEDL.H header file, the
  1151.     WEDL-E.DLL library file, and the WEDL-E.LIB import library file.
  1152.  
  1153.     First, you must first compile the source code file(s) into object code
  1154.     file(s).  Sample compiler command lines are:
  1155.  
  1156.         cl -c -AS -Gsw -Ox -Zpe -W3 demo.c
  1157.         bcc -c -ms -w -WS -O -Z demo.c
  1158.  
  1159.     Second, you must link object modules together to create an executable
  1160.     program.  Sample linker command lines are:
  1161.  
  1162.         link /NOD demo, demo, demo, libw slibcew wedl-e, demo
  1163.         tlink /Twe /v /n /c c0ws demo,demo,,cwins cs import maths \
  1164.                 wedl-e, demo
  1165.  
  1166.     Finally, you must bind your resources to your executable program using a
  1167.     resource compiler.  A sample resource compiler command line is:
  1168.  
  1169.         rc demo
  1170.  
  1171.  
  1172.     Executing the Program
  1173.  
  1174.     When executing your program that uses WEDL, the only requirement is that
  1175.     the library file WEDL-E.DLL be in the current directory or in the PATH.
  1176.  
  1177.  
  1178.     Common Programming Errors
  1179.  
  1180.     There are a few common programming errors when using the WEDL library.
  1181.     These include:
  1182.  
  1183.     1.  You have a field that is larger than the character string buffer
  1184.     receiving the fields contents.  For example, if you have a phone number
  1185.     field defined like so:
  1186.  
  1187.         char phone_num[10];             // error - not large enough!
  1188.  
  1189.  
  1190.                                       22   
  1191.         field_define( hform, ID_PHONE, phone_num, DT_STRING,
  1192.                       "'('999')'999'-'9999", FDF_NONE, NULL, 0, 0 );
  1193.  
  1194.     When the user selects "OK", WEDL will copy the contents of the field
  1195.     plus a terminating '\0' character to 'phone_num'.  This means 11
  1196.     characters will be copied to a character string buffer only 10
  1197.     characters wide.  Changing 'phone_num' to an array of 11 characters will
  1198.     fix this problem. Suppose your phone number field is defined like:
  1199.  
  1200.         char phone_num[11];             // error - not large enough!
  1201.         field_define( hform, ID_PHONE, phone_num, DT_STRING,
  1202.                       "'('999')'999'-'9999", FDF_WRPHYS, NULL, 0, 0 );
  1203.  
  1204.     Now you have the same problem, but in a different way.  Since the
  1205.     FDF_WRPHYS feature is being used, the formatting characters '(', ')',
  1206.     and '-' will be copied to 'phone_num' as well.  This means 'phone_num'
  1207.     must be 14 characters wide.
  1208.  
  1209.     2.  Your form handle variable is not declared properly.  The 'hform'
  1210.     variable must be static or global.  Otherwise, it may not work.  This
  1211.     declaration is a no-no:
  1212.  
  1213.         int FAR PASCAL DialogProc( HWND hDlg, unsigned message, WORD wParam,
  1214.                                    LONG lParam )
  1215.         {
  1216.             HFORM hform;            //  error - not static!
  1217.             // ....the rest of the code
  1218.  
  1219.     As soon as WM_INITDIALOG returns, the value of 'hform' will be lost and
  1220.     later when the dproc_enter_wm_command function is called, it will be
  1221.     passed an invalid form handle.  Either change the declaration of 'hform'
  1222.     to static or make 'hform' a global variable.
  1223.  
  1224.     3.  A call to the field_define function keeps failing.  This is most
  1225.     likely occurring because your field's picture string is invalid or is
  1226.     invalid for the given field feature(s).  Check the picture string
  1227.     against the allowable characters listed in Appendix A.
  1228.  
  1229.     4.  You have a field in update mode (FDF_UPDATE or FDF_CONDUPD) and are
  1230.     getting garbage characters in the fields.  For example:
  1231.  
  1232.         char ssn[10];
  1233.         field_define( hform, ID_SOCSEC, ssn, DT_STRING,
  1234.                       "999'-'99'-'9999", FDF_UPDATE, NULL, 0, 0 );
  1235.  
  1236.     Here you would have a problem.  The variable 'ssn' has not been
  1237.     initialized, yet you have the field in update mode.  The field would be
  1238.     initialized with whatever garbage contents 'ssn' happens to contain.
  1239.     Make sure the variables you are updating actually have valid values.
  1240.     Otherwise, do not use update mode.
  1241.  
  1242.     5.  Your program locks up while in your validation function.  This is
  1243.     most likely the result of you calling a Windows function which generates
  1244.  
  1245.  
  1246.                                       23   
  1247.     messages that get sent to either the dialog procedure or the edit
  1248.     control procedure.  Some Windows function calls will work during a
  1249.     validation function; others will not.  You will have to experiment for
  1250.     yourself.
  1251.  
  1252.     6.  The data type you specified in the data_type parameter of the
  1253.     field_define function does not match the data type pointed to by the
  1254.     pdata pointer.  For example:
  1255.  
  1256.         long age;
  1257.         field_define( hform, ID_AGE, &age, DT_INTEGER,
  1258.                       "999", FDF_NONE, NULL, 0, 0 );
  1259.  
  1260.     Here the address of 'age', which is a long, is passed to field_define,
  1261.     yet the data_type was specified as an integer.  This will cause real
  1262.     problems.
  1263.  
  1264.     7.  You defined a combo box field without specifying FDF_COMBO as one of
  1265.     the field's features. The field will not function properly unless
  1266.     FDF_COMBO is specified.
  1267.  
  1268.     8.  You have a combo box field with formatting characters in the picture
  1269.     string.  Normally, the only characters that you should have in a picture
  1270.     string for a combo box field are validation characters. If you do use
  1271.     formatting characters, the strings contained in the combo box's list box
  1272.     must have the same format as the picture string.
  1273.  
  1274.  
  1275.  
  1276.  
  1277.  
  1278.  
  1279.  
  1280.  
  1281.  
  1282.  
  1283.  
  1284.  
  1285.  
  1286.  
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.                                       24   
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.  
  1328.                               Function Reference
  1329.  
  1330.  
  1331.  
  1332.  
  1333.  
  1334.  
  1335.  
  1336.  
  1337.  
  1338.  
  1339.  
  1340.  
  1341.  
  1342.  
  1343.  
  1344.  
  1345.  
  1346.  
  1347.  
  1348.  
  1349.  
  1350.  
  1351.  
  1352.  
  1353.  
  1354.  
  1355.  
  1356.  
  1357.  
  1358.                                       25   
  1359.  
  1360.     button_define
  1361.  
  1362.     Syntax      HBUTTON    button_define(hform, ctrl_id, pdata, group_id,
  1363.                 on_value, off_value, init_state, help_context)
  1364.  
  1365.                 Defines a button.
  1366.  
  1367.                 Parameter       Type/Description
  1368.                 ---------       ----------------
  1369.                 hform           HFORM    The form's handle.
  1370.  
  1371.                 ctrl_id         int    The dialog control ID of the button
  1372.                                 or check box control being defined.
  1373.  
  1374.                 pdata           LPINT    Pointer to the integer variable
  1375.                                 that will be automatically initialized or
  1376.                                 updated by the button control.  If NULL is
  1377.                                 given, the button will not manipulate any
  1378.                                 variables and the button's value will have
  1379.                                 to be retrieved manually.
  1380.  
  1381.                 group_id        int    An identifier specifying the group
  1382.                                 the button belongs to.  For example, if
  1383.                                 there was a group box containing 2 radio
  1384.                                 buttons, one for "Male" and the other for
  1385.                                 "Female", you'd define both of their buttons
  1386.                                 with the same pdata and group_id.  If the
  1387.                                 button does not belong to a group, set
  1388.                                 group_id to 0.
  1389.  
  1390.                 on_value        int    The value that will be stored at the
  1391.                                 integer pointed to by pdata if the button is
  1392.                                 checked.
  1393.  
  1394.                 off_value       int    The value that will be stored at the
  1395.                                 integer variable pointed to by pdata if the
  1396.                                 button is not checked.  If the button
  1397.                                 control belongs to a group (group_id is
  1398.                                 nonzero), the value given for off_value is
  1399.                                 ignored.
  1400.  
  1401.                 init_state      int    The initial state of the button
  1402.                                 control.  Can be one of the following
  1403.                                 values:
  1404.  
  1405.                                 Value       Meaning
  1406.                                 -----       -------
  1407.                                 BS_OFF      Button will be initialized off
  1408.                                             (not checked).
  1409.  
  1410.                                 BS_ON       Button will be initialized on
  1411.                                             (checked).
  1412.  
  1413.  
  1414.                                       26   
  1415.  
  1416.                                 BS_GRAYED   Button will be grayed (disabled)
  1417.                                             if it is a 3-state button.
  1418.  
  1419.                                 BS_USEDATA  Button will be initialized to
  1420.                                             the value of the integer pointed
  1421.                                             to by pdata.  If the value is
  1422.                                             equal to the on_value, the
  1423.                                             button will be initialized on.
  1424.                                             Otherwise, the button will be
  1425.                                             initialized off.
  1426.  
  1427.                                 BS_NOTSET   Button's state will not be set.
  1428.  
  1429.                 help_context    DWORD    The help context identifier of the
  1430.                                 Windows Help topic associated with the
  1431.                                 button.  If context-sensitive help is not
  1432.                                 being applied to the button, set
  1433.                                 help_context to 0.  If context-sensitive
  1434.                                 help is being applied to the button, the
  1435.                                 form_set_help function must be called prior
  1436.                                 to the F1 key being pressed.
  1437.  
  1438.     Return Value    The handle of the new button's record or NULL if an
  1439.                     error occurred.  An error can be caused by one of the
  1440.                     following conditions:
  1441.  
  1442.                         Control ID is invalid.
  1443.                         The form_end function has already been called.
  1444.                         Memory allocation error.
  1445.  
  1446.     ________________________________________________________________________
  1447.  
  1448.     button_get_check
  1449.  
  1450.     Syntax      int    button_get_check(hbutton)
  1451.  
  1452.                 Gets the check state of a button.
  1453.  
  1454.                 Parameter       Type/Description
  1455.                 ---------       ----------------
  1456.                 hbutton         HBUTTON    The button's handle.
  1457.  
  1458.     Return Value    BS_OFF if the button is off (not checked), BS_ON if the
  1459.                     button is on (checked), or -1 if an error occurred.
  1460.  
  1461.     ________________________________________________________________________
  1462.  
  1463.     button_get_from_ctrl_id
  1464.  
  1465.     Syntax      HBUTTON    button_get_from_ctrl_id(hform, ctrl_id)
  1466.  
  1467.                 Gets the handle of a button using its dialog control ID as
  1468.  
  1469.  
  1470.                                       27   
  1471.                 input.
  1472.  
  1473.                 Parameter       Type/Description
  1474.                 ---------       ----------------
  1475.                 hform           HFORM    The form's handle.
  1476.  
  1477.                 ctrl_id         int    The dialog control ID of the control
  1478.                                 the button is associated with.
  1479.  
  1480.     Return Value    The handle of the button associated with the input
  1481.                     dialog control ID or NULL if an error occurred.
  1482.  
  1483.     ________________________________________________________________________
  1484.  
  1485.     button_get_from_group
  1486.  
  1487.     Syntax      HBUTTON    button_get_from_group(hform, group_id)
  1488.  
  1489.                 Gets the handle of the checked button in a group of buttons.
  1490.  
  1491.                 Parameter       Type/Description
  1492.                 ---------       ----------------
  1493.                 hform           HFORM    The form's handle.
  1494.  
  1495.                 group_id        int    The group ID of the group of buttons
  1496.                                 to test.
  1497.  
  1498.     Return Value    The handle of the button that is checked or NULL if an
  1499.                     error occurred.
  1500.  
  1501.     ________________________________________________________________________
  1502.  
  1503.     button_get_from_hwnd
  1504.  
  1505.     Syntax      HBUTTON    button_get_from_hwnd(hform, hWnd)
  1506.  
  1507.                 Gets the handle of a button using the window handle of its
  1508.                 control as input.
  1509.  
  1510.                 Parameter       Type/Description
  1511.                 ---------       ----------------
  1512.                 hform           HFORM    The form's handle.
  1513.  
  1514.                 hWnd            HWND    The window handle of the control
  1515.                                 associated with the button.
  1516.  
  1517.     Return Value    The handle of the button associated with the input
  1518.                     window handle or NULL if an error occurred.
  1519.  
  1520.     ________________________________________________________________________
  1521.  
  1522.     button_has_changed
  1523.  
  1524.  
  1525.  
  1526.                                       28   
  1527.     Syntax      int    button_has_changed(hbutton)
  1528.  
  1529.                 Determines whether a button has been changed by the user.
  1530.  
  1531.                 Parameter       Type/Description
  1532.                 ---------       ----------------
  1533.                 hbutton         HBUTTON    The button's handle.
  1534.  
  1535.     Return Value    TRUE if the user has changed the button, FALSE if the
  1536.                     user has not changed the button, or -1 if an error
  1537.                     occurred.
  1538.  
  1539.     ________________________________________________________________________
  1540.  
  1541.     button_lock
  1542.  
  1543.     Syntax      LPBUTTON    button_lock(hbutton)
  1544.  
  1545.                 Locks a button's record in memory so it can be accessed.
  1546.  
  1547.                 Parameter       Type/Description
  1548.                 ---------       ----------------
  1549.                 hbutton         HBUTTON    The button's handle.
  1550.  
  1551.     Return Value    A far pointer to the button's record or NULL if an error
  1552.                     occurred.  See the description for the BUTTON struct for
  1553.                     details.
  1554.  
  1555.     Comments    Once you have obtained a pointer to the button's record, you
  1556.                 are able to read or change any of the record's elements.
  1557.                 However, it is not recommended that you change the values of
  1558.                 any of the elements.
  1559.  
  1560.                 When you are done accessing the button's record, be sure to
  1561.                 call button_unlock.
  1562.  
  1563.                 Calling this function locks the button's record in the
  1564.                 .DLL's local heap.  In addition, the .DLL's entire data
  1565.                 segment is locked in the global heap.  This is required to
  1566.                 ensure the returned far pointer will remain valid until the
  1567.                 call to button_unlock.  For this reason, you should not keep
  1568.                 the button locked any longer than absolutely necessary.
  1569.  
  1570.     ________________________________________________________________________
  1571.  
  1572.     button_set_check
  1573.  
  1574.     Syntax      int    button_set_check(hbutton, state)
  1575.  
  1576.                 Sets the check state of a button.
  1577.  
  1578.                 Parameter       Type/Description
  1579.                 ---------       ----------------
  1580.  
  1581.  
  1582.                                       29   
  1583.                 hbutton         HBUTTON    The button's handle.
  1584.  
  1585.                 state           int    The state to set the button control
  1586.                                 to.  See the description of the
  1587.                                 button_define function for a list of valid
  1588.                                 state values.
  1589.  
  1590.     Return Value    Nonzero if an error occurred.
  1591.  
  1592.     ________________________________________________________________________
  1593.  
  1594.     button_unlock
  1595.  
  1596.     Syntax      void    button_unlock(hbutton)
  1597.  
  1598.                 Unlocks a button's record in memory.
  1599.  
  1600.                 Parameter       Type/Description
  1601.                 ---------       ----------------
  1602.                 hbutton         HBUTTON    The button's handle.
  1603.  
  1604.     Return Value    None.
  1605.  
  1606.     ________________________________________________________________________
  1607.  
  1608.     char_is_printable
  1609.  
  1610.     Syntax      BOOL    char_is_printable(ch)
  1611.  
  1612.                 Determines whether a character is printable.  This
  1613.                 determination is made based upon Windows' current language
  1614.                 driver settings.
  1615.  
  1616.                 Parameter       Type/Description
  1617.                 ---------       ----------------
  1618.                 ch              int    The character to test.
  1619.  
  1620.     Return Value    TRUE if the character is printable; otherwise FALSE.
  1621.  
  1622.     ________________________________________________________________________
  1623.  
  1624.     char_to_lower
  1625.  
  1626.     Syntax      int    char_to_lower(ch)
  1627.  
  1628.                 Converts a character to lowercase.  This conversion is made
  1629.                 based upon Windows' current language driver settings.
  1630.  
  1631.                 Parameter       Type/Description
  1632.                 ---------       ----------------
  1633.                 ch              int    The character to convert.
  1634.  
  1635.     Return Value    The converted character.
  1636.  
  1637.  
  1638.                                       30   
  1639.  
  1640.     ________________________________________________________________________
  1641.  
  1642.     char_to_upper
  1643.  
  1644.     Syntax      int    char_to_upper(ch)
  1645.  
  1646.                 Converts a character to uppercase.  This conversion is made
  1647.                 based upon Windows' current language driver settings.
  1648.  
  1649.                 Parameter       Type/Description
  1650.                 ---------       ----------------
  1651.                 ch              int    The character to convert.
  1652.  
  1653.     Return Value    The converted character.
  1654.  
  1655.     ________________________________________________________________________
  1656.  
  1657.     dproc_enter_error
  1658.  
  1659.     Syntax      int    dproc_enter_error(hform)
  1660.  
  1661.                 This function is part of the dialog procedure's framework.
  1662.                 It must be the first function called in a field's error
  1663.                 handler.
  1664.  
  1665.                 Parameter       Type/Description
  1666.                 ---------       ----------------
  1667.                 hform           HFORM    The form's handle.
  1668.  
  1669.     Return Value    Nonzero if an error occurred.
  1670.  
  1671.     ________________________________________________________________________
  1672.  
  1673.     dproc_enter_idcancel
  1674.  
  1675.     Syntax      int    dproc_enter_idcancel(hform)
  1676.  
  1677.                 This function is part of the dialog procedure's framework.
  1678.                 It must be the first function called in the IDCANCEL
  1679.                 processing of the WM_COMMAND message.
  1680.  
  1681.                 Parameter       Type/Description
  1682.                 ---------       ----------------
  1683.                 hform           HFORM    The form's handle.
  1684.  
  1685.     Return Value    Nonzero if an error occurred.
  1686.  
  1687.     ________________________________________________________________________
  1688.  
  1689.     dproc_enter_idok
  1690.  
  1691.     Syntax      int    dproc_enter_idok(hform)
  1692.  
  1693.  
  1694.                                       31   
  1695.  
  1696.                 This function is part of the dialog procedure's framework.
  1697.                 It must be the first function called in the IDOK processing
  1698.                 of the WM_COMMAND message.
  1699.  
  1700.                 Parameter       Type/Description
  1701.                 ---------       ----------------
  1702.                 hform           HFORM    The form's handle.
  1703.  
  1704.     Return Value    Nonzero if an error occurred.
  1705.  
  1706.     ________________________________________________________________________
  1707.  
  1708.     dproc_enter_wm_command
  1709.  
  1710.     Syntax      int    dproc_enter_wm_command(hform, wParam, lParam)
  1711.  
  1712.                 This function is part of the dialog procedure's framework.
  1713.                 It must be the first function called in the WM_COMMAND
  1714.                 message processing.
  1715.  
  1716.                 Parameter       Type/Description
  1717.                 ---------       ----------------
  1718.                 hform           HFORM    The form's handle.
  1719.  
  1720.                 wParam          unsigned    The wParam parameter passed to
  1721.                                 the dialog procedure by Windows.
  1722.  
  1723.                 lParam          LONG    The lParam parameter passed to the
  1724.                                 dialog procedure by Windows.
  1725.  
  1726.     Return Value    Nonzero if an error occurred.
  1727.  
  1728.     ________________________________________________________________________
  1729.  
  1730.     dproc_exit_error
  1731.  
  1732.     Syntax      int    dproc_exit_error(hform, lParam)
  1733.  
  1734.                 This function is part of the dialog procedure's framework.
  1735.                 It must be the last function called in a field's error
  1736.                 handler.
  1737.  
  1738.                 Parameter       Type/Description
  1739.                 ---------       ----------------
  1740.                 hform           HFORM    The form's handle.
  1741.  
  1742.                 lParam          LONG    The lParam parameter passed to the
  1743.                                 dialog procedure by Windows.
  1744.  
  1745.     Return Value    Nonzero if an error occurred.
  1746.  
  1747.     ________________________________________________________________________
  1748.  
  1749.  
  1750.                                       32   
  1751.  
  1752.     field_data_to_log
  1753.  
  1754.     Syntax      int    field_data_to_log(hfield, pbuf, pdata, data_type)
  1755.  
  1756.                 Converts a value in a specified data type to a character
  1757.                 string in logical field format.
  1758.  
  1759.                 Parameter       Type/Description
  1760.                 ---------       ----------------
  1761.                 hfield          HFIELD    The field's handle.
  1762.  
  1763.                 pbuf            LPSTR    Pointer to the buffer to receive
  1764.                                 the converted value.
  1765.  
  1766.                 pdata           LPVOID    Pointer to the data item to
  1767.                                 containing the data to convert. This
  1768.                                 parameter can point to one of the following
  1769.                                 types:  char (string), int, unsigned, long,
  1770.                                 unsigned long, or double.  The value you
  1771.                                 give for the data_type parameter must
  1772.                                 correspond to the data pointed to by pdata.
  1773.  
  1774.                 data_type       int    Specifies the data type pdata points
  1775.                                 to.  See the description of the field_define
  1776.                                 function for a list of possible values.
  1777.  
  1778.     Return Value    Nonzero if an error occurred.
  1779.  
  1780.     ________________________________________________________________________
  1781.  
  1782.     field_define
  1783.  
  1784.     Syntax      HFIELD    field_define(hform, ctrl_id, pdata, data_type,
  1785.                 picture_string, features, pvalid_func, error_value,
  1786.                 help_context)
  1787.  
  1788.                 Defines a field.  This function is called for each edit
  1789.                 control in your dialog box you want to define.
  1790.  
  1791.                 Parameter       Type/Description
  1792.                 ---------       ----------------
  1793.                 hform           HFORM    The form's handle.
  1794.  
  1795.                 ctrl_id         int    The dialog control ID of the edit
  1796.                                 control you want to define.
  1797.  
  1798.                 pdata           LPVOID    Pointer to the data item you are
  1799.                                 going to initialize or update. This
  1800.                                 parameter can point to one of the following
  1801.                                 types:  char (string), int, unsigned, long,
  1802.                                 unsigned long, or double.  It can also be
  1803.                                 NULL if you do not want any data modified by
  1804.  
  1805.  
  1806.                                       33   
  1807.                                 the field.  The value you give for the
  1808.                                 data_type parameter must correspond to the
  1809.                                 data pointed to by pdata.
  1810.  
  1811.                 data_type       int    Specifies the data type pdata points
  1812.                                 to.  Can be one of the following values:
  1813.  
  1814.                                 Value       Meaning
  1815.                                 -----       -------
  1816.                                 DT_NULL     The pdata parameter is NULL.
  1817.  
  1818.                                 DT_STRING   pdata points to a character
  1819.                                             string.  The string must be
  1820.                                             terminated with a '\0' if you
  1821.                                             are updating existing data.
  1822.  
  1823.                                 DT_INTEGER  pdata points to a signed
  1824.                                             integer.
  1825.  
  1826.                                 DT_UNSIGNED pdata points to an unsigned
  1827.                                             integer.
  1828.  
  1829.                                 DT_LONG     pdata points to a signed long
  1830.                                             integer.
  1831.  
  1832.                                 DT_ULONG    pdata points to an unsigned long
  1833.                                             integer.
  1834.  
  1835.                                 DT_DOUBLE   pdata points to a double-
  1836.                                             precision real number.
  1837.  
  1838.                 picture_string  LPSTR    The field's picture string.  The
  1839.                                 picture string describes the allowable
  1840.                                 characters for each position in the field,
  1841.                                 the size of the field, and the positioning
  1842.                                 of the formatting characters.  See Appendix
  1843.                                 A for a list of characters you can use in
  1844.                                 the picture string.
  1845.  
  1846.                 features        DWORD    One or more features describing how
  1847.                                 the field should behave.  You can combine
  1848.                                 features with the bitwise OR operator. Can
  1849.                                 be one or more of the following values:
  1850.  
  1851.                                 Value           Meaning
  1852.                                 -----           -------
  1853.                                 FDF_NONE        No features defined.
  1854.  
  1855.                                 FDF_COMPLETE    Field must be complete (no
  1856.                                                 blanks allowed unless
  1857.                                                 specified in the picture
  1858.                                                 string).
  1859.  
  1860.  
  1861.  
  1862.                                       34   
  1863.                                 FDF_NOTBLANK    Field cannot be blank.
  1864.  
  1865.                                 FDF_NOTZERO     Field cannot be zero.
  1866.  
  1867.                                 FDF_NOTEDIT     Field cannot be edited.
  1868.                                                 Normally this feature is
  1869.                                                 combined with FDF_UPDATE.
  1870.  
  1871.                                 FDF_MUSTEDIT    Field must be edited.
  1872.  
  1873.                                 FDF_UPDATE      Update existing data.  This
  1874.                                                 initializes the edit control
  1875.                                                 with the data pointed to by
  1876.                                                 pdata.
  1877.  
  1878.                                 FDF_CONDUPD     Conditionally update
  1879.                                                 existing data.  This
  1880.                                                 initializes the edit control
  1881.                                                 with the data pointed to by
  1882.                                                 pdata.  When the user enters
  1883.                                                 the field, the cursor is
  1884.                                                 placed after the last
  1885.                                                 character in the field.  If
  1886.                                                 a character is entered, the
  1887.                                                 field is cleared and the
  1888.                                                 cursor is placed in the
  1889.                                                 first position of the field.
  1890.                                                 If an editing key is
  1891.                                                 pressed, the field is set to
  1892.                                                 update mode.
  1893.  
  1894.                                 FDF_SPCFILL     Space-fill field from the
  1895.                                                 right.  The data_type must
  1896.                                                 be DT_STRING.
  1897.  
  1898.                                 FDF_ZEROFILL    Zero-fill numeric field from
  1899.                                                 the left. FDF_NUMERIC or
  1900.                                                 FDF_CALCNUM must also be
  1901.                                                 specified.
  1902.  
  1903.                                 FDF_BLNKZERO    Blank numeric field if equal
  1904.                                                 to zero. FDF_NUMERIC or
  1905.                                                 FDF_CALCNUM must also be
  1906.                                                 specified.
  1907.  
  1908.                                 FDF_RDPHYS      The DT_STRING variable
  1909.                                                 pointed to by pdata is
  1910.                                                 already in physical field
  1911.                                                 format (has embedded
  1912.                                                 formatting characters).
  1913.  
  1914.                                 FDF_WRPHYS      Merges a DT_STRING field's
  1915.                                                 formatting characters into
  1916.  
  1917.  
  1918.                                       35   
  1919.                                                 its logical contents when
  1920.                                                 storing it.  The destination
  1921.                                                 character buffer will then
  1922.                                                 contain the field's physical
  1923.                                                 contents.
  1924.  
  1925.                                 FDF_UPPER       Characters enters into the
  1926.                                                 field will be converted to
  1927.                                                 uppercase.
  1928.  
  1929.                                 FDF_LOWER       Characters entered into the
  1930.                                                 field will be converted to
  1931.                                                 lowercase.
  1932.  
  1933.                                 FDF_MIXED       Characters entered into the
  1934.                                                 field will be converted to
  1935.                                                 uppercase or lowercase
  1936.                                                 depending upon the previous
  1937.                                                 character.  The Shift keys
  1938.                                                 override the conversion.
  1939.  
  1940.                                 FDF_NUMERIC     Field is a standard numeric
  1941.                                                 field.
  1942.  
  1943.                                 FDF_CALCNUM     Field is a calculator-style
  1944.                                                 numeric field. Digits to the
  1945.                                                 left of the decimal are
  1946.                                                 shifted to the left as
  1947.                                                 digits are entered.
  1948.  
  1949.                                 FDF_VAFFLD      Do not perform validation
  1950.                                                 until the user tries to
  1951.                                                 leave the field.
  1952.  
  1953.                                 FDF_VAFFRM      Do not perform validation
  1954.                                                 until the user selects "OK".
  1955.  
  1956.                                 FDF_COMBO       Field belongs to a combo
  1957.                                                 box. Use caution when
  1958.                                                 defining a combo box field
  1959.                                                 with embedded formatting
  1960.                                                 characters - strings in the
  1961.                                                 combo box's list box must
  1962.                                                 have the same format as the
  1963.                                                 picture string.
  1964.  
  1965.                 pvalid_func     int (FAR PASCAL *) (LPSTR)    The procedure-
  1966.                                 instance address of the field's validation
  1967.                                 function or NULL if there is no validation
  1968.                                 function. This cannot be the address of the
  1969.                                 validation function itself. A procedure-
  1970.                                 instance address must be created using
  1971.                                 MakeProcInstance and this is the value given
  1972.  
  1973.  
  1974.                                       36   
  1975.                                 here.  See the following "Comments" section
  1976.                                 for details.
  1977.  
  1978.                 error_value     int    This is the value that is passed to
  1979.                                 the dialog procedure when the validation
  1980.                                 function returns an error.  The error_value
  1981.                                 is located in the wParam parameter of the
  1982.                                 WM_COMMAND message sent to the dialog
  1983.                                 procedure.  If pvalid_func is NULL, the
  1984.                                 value given for error_value is ignored.
  1985.  
  1986.                 help_context    DWORD    The help context identifier of the
  1987.                                 Windows Help topic associated with the
  1988.                                 field.  If context-sensitive help is not
  1989.                                 being applied to the field, set help_context
  1990.                                 to 0.  If context-sensitive help is being
  1991.                                 applied to the field, the form_set_help
  1992.                                 function must be called prior to the F1 key
  1993.                                 being pressed.
  1994.  
  1995.     Return Value    The handle of the new field's record or NULL if an error
  1996.                     occurred.  An error can be caused by one of the
  1997.                     following conditions:
  1998.  
  1999.                         Picture string is invalid or invalid for the
  2000.                         specified field feature(s).
  2001.                         Control ID is invalid.
  2002.                         The form_end function has already been called.
  2003.                         Memory allocation error.
  2004.  
  2005.     Comments    You must make all calls to this function during your dialog
  2006.                 procedure's WM_INITDIALOG message processing between the
  2007.                 calls to form_begin and form_end.
  2008.  
  2009.                 The validation function must use the Pascal calling
  2010.                 convention and must be declared FAR.  The validation
  2011.                 function must have the following form:
  2012.  
  2013.     Validation  int FAR PASCAL ValidationFunc(LPSTR pbuf)
  2014.     Function
  2015.                 ValidationFunc represents the validation function's name.
  2016.                 The name of the validation function must be listed in an
  2017.                 EXPORTS statement in the program's module definition file.
  2018.                 pbuf represents the validation function's parameter name.
  2019.  
  2020.                 The validation function is used to validate a field.  When
  2021.                 the user tries to leave the field, ValidationFunc is called
  2022.                 and passed a pointer, pbuf, which points to a buffer
  2023.                 containing the current logical contents of the field.  The
  2024.                 ValidationFunc then validates the field's logical contents
  2025.                 and returns zero if no error was found or the logical
  2026.                 position of the error + 1.
  2027.  
  2028.  
  2029.  
  2030.                                       37   
  2031.                 Parameter       Description
  2032.                 ---------       -----------
  2033.                 pbuf            Pointer to the buffer containing the field's
  2034.                                 current logical contents.
  2035.  
  2036.                 Return Value
  2037.  
  2038.                 Zero if the field passed validation, or the logical position
  2039.                 of the error in the field + 1.
  2040.  
  2041.                 Comments
  2042.  
  2043.                 Modifying the data pointed to by pbuf will have no effect on
  2044.                 the contents of the field.
  2045.  
  2046.     ________________________________________________________________________
  2047.  
  2048.     field_disable_feature
  2049.  
  2050.     Syntax      int    field_disable_feature(hfield, feature)
  2051.  
  2052.                 Disables one or more of a field's features.
  2053.  
  2054.                 Parameter       Type/Description
  2055.                 ---------       ----------------
  2056.                 hfield          HFIELD    The field's handle.
  2057.  
  2058.                 feature         DWORD    The feature to disable.  To disable
  2059.                                 multiple features, combine them with the
  2060.                                 bitwise OR operator.  See the description of
  2061.                                 the field_define function for a list of
  2062.                                 features that can be specified.
  2063.  
  2064.     Return Value    Nonzero if an error occurred.
  2065.  
  2066.     ________________________________________________________________________
  2067.  
  2068.     field_enable_feature
  2069.  
  2070.     Syntax      int    field_enable_feature(hfield, feature)
  2071.  
  2072.                 Enables one or more of a field's features.
  2073.  
  2074.                 Parameter       Type/Description
  2075.                 ---------       ----------------
  2076.                 hfield          HFIELD    The field's handle.
  2077.  
  2078.                 feature         DWORD    The feature to enable.  To enable
  2079.                                 multiple features, combine them with the
  2080.                                 bitwise OR operator.  See the description of
  2081.                                 the field_define function for a list of
  2082.                                 features that can be specified.
  2083.  
  2084.  
  2085.  
  2086.                                       38   
  2087.     Return Value    Nonzero if an error occurred.
  2088.  
  2089.     ________________________________________________________________________
  2090.  
  2091.     field_get_character
  2092.  
  2093.     Syntax      int    field_get_character(hfield, position, physical)
  2094.  
  2095.                 Gets a character from the contents of a field.
  2096.  
  2097.                 Parameter       Type/Description
  2098.                 ---------       ----------------
  2099.                 hfield          HFIELD    The field's handle.
  2100.  
  2101.                 position        int    The logical or physical position from
  2102.                                 which the character will be retrieved.
  2103.  
  2104.                 physical        BOOL    TRUE if position is a physical
  2105.                                 position.  FALSE if position is a logical
  2106.                                 position.
  2107.  
  2108.     Return Value    The specified character or -1 if an error occurred.
  2109.  
  2110.     ________________________________________________________________________
  2111.  
  2112.     field_get_decimal_pos
  2113.  
  2114.     Syntax      int    field_get_decimal_pos(hfield)
  2115.  
  2116.                 Gets the virtual logical position of the decimal point in a
  2117.                 field.  For example if a field had a picture string of
  2118.                 "####.##", the virtual logical position of the decimal point
  2119.                 would be 4. For "###", it would be 3.
  2120.  
  2121.                 Parameter       Type/Description
  2122.                 ---------       ----------------
  2123.                 hfield          HFIELD    The field's handle.
  2124.  
  2125.     Return Value    The virtual logical position of the decimal point or -1
  2126.                     if an error occurred.
  2127.  
  2128.     ________________________________________________________________________
  2129.  
  2130.     field_get_from_ctrl_id
  2131.  
  2132.     Syntax      HFIELD    field_get_from_ctrl_id(hform, ctrl_id)
  2133.  
  2134.                 Gets the handle for a field associated with a given dialog
  2135.                 control ID.
  2136.  
  2137.                 Parameter       Type/Description
  2138.                 ---------       ----------------
  2139.                 hform           HFORM    The form's handle.
  2140.  
  2141.  
  2142.                                       39   
  2143.  
  2144.                 ctrl_id         int    The dialog control ID of the field's
  2145.                                 edit control.
  2146.  
  2147.     Return Value    The handle of the field associated with the input dialog
  2148.                     control ID or NULL if an error occurred.
  2149.  
  2150.     ________________________________________________________________________
  2151.  
  2152.     field_get_from_hwnd
  2153.  
  2154.     Syntax      HFIELD    field_get_from_hwnd(hform, hWnd)
  2155.  
  2156.                 Gets the handle for a field associated with a given edit
  2157.                 control's window handle.
  2158.  
  2159.                 Parameter       Type/Description
  2160.                 ---------       ----------------
  2161.                 hform           HFORM    The form's handle.
  2162.  
  2163.                 hWnd            HWND    The window handle of the field's
  2164.                                 edit control.
  2165.  
  2166.     Return Value    The handle of the field associated with the input window
  2167.                     handle or NULL if an error occurred.
  2168.  
  2169.     ________________________________________________________________________
  2170.  
  2171.     field_get_pos_info
  2172.  
  2173.     Syntax      int    field_get_pos_info(hfield, logical_position, pfpos)
  2174.  
  2175.                 Gets information related to a field's logical position.
  2176.                 This information includes the physical position, selection,
  2177.                 picture string position, validation character, validation
  2178.                 character occurrence, and which side of the decimal point
  2179.                 the position lies.
  2180.  
  2181.                 Parameter           Type/Description
  2182.                 ---------           ----------------
  2183.                 hfield              HFIELD    The field's handle.
  2184.  
  2185.                 logical_position    int    The logical position to get
  2186.                                     information for.
  2187.  
  2188.                 pfpos               LPFIELD_POS    A pointer to the
  2189.                                     FIELD_POS struct which will receive the
  2190.                                     information.  See the description of the
  2191.                                     FIELD_POS structure for details.
  2192.  
  2193.     Return Value    Nonzero if an error occurred.
  2194.  
  2195.     ________________________________________________________________________
  2196.  
  2197.  
  2198.                                       40   
  2199.  
  2200.     field_get_position
  2201.  
  2202.     Syntax      int    field_get_position(hfield, pfpos)
  2203.  
  2204.                 Gets information related to the current position in a field.
  2205.                 This information includes the logical position, physical
  2206.                 position, selection, picture string position, validation
  2207.                 character, validation character occurrence, and which side
  2208.                 of the decimal point the position lies.
  2209.  
  2210.                 Parameter       Type/Description
  2211.                 ---------       ----------------
  2212.                 hfield          HFIELD    The field's handle.
  2213.  
  2214.                 pfpos           LPFIELD_POS    A pointer to the FIELD_POS
  2215.                                 struct which will receive the information.
  2216.                                 See the description of the FIELD_POS
  2217.                                 structure for details.
  2218.  
  2219.     Return Value    Nonzero if an error occurred.
  2220.  
  2221.     Comments    The field identified by hfield must have the focus when
  2222.                 calling this function.
  2223.  
  2224.     ________________________________________________________________________
  2225.  
  2226.     field_get_text
  2227.  
  2228.     Syntax      int    field_get_text(hfield, pbuf, physical)
  2229.  
  2230.                 Gets the contents of a field.
  2231.  
  2232.                 Parameter       Type/Description
  2233.                 ---------       ----------------
  2234.                 hfield          HFIELD    The field's handle.
  2235.  
  2236.                 pbuf            LPSTR    Pointer to the buffer to receives
  2237.                                 the field's contents.
  2238.  
  2239.                 physical        BOOL    TRUE specifies physical contents are
  2240.                                 to be copied to pbuf. FALSE specifies
  2241.                                 logical contents are to be copied.
  2242.  
  2243.     Return Value    Nonzero if an error occurred.
  2244.  
  2245.     ________________________________________________________________________
  2246.  
  2247.     field_has_changed
  2248.  
  2249.     Syntax      int    field_has_changed(hfield)
  2250.  
  2251.                 Determines whether a field has been edited by the user.
  2252.  
  2253.  
  2254.                                       41   
  2255.  
  2256.                 Parameter       Type/Description
  2257.                 ---------       ----------------
  2258.                 hfield          HFIELD    The field's handle.
  2259.  
  2260.     Return Value    TRUE if the user has edited the field, FALSE if the user
  2261.                     has not edited the field, or -1 if an error occurred.
  2262.  
  2263.     ________________________________________________________________________
  2264.  
  2265.     field_insert_decimal
  2266.  
  2267.     Syntax      int    field_insert_decimal(hfield, pbuf)
  2268.  
  2269.                 Inserts a decimal point into a buffer containing a numeric
  2270.                 field's logical contents.
  2271.  
  2272.                 Parameter       Type/Description
  2273.                 ---------       ----------------
  2274.                 hfield          HFIELD    The field's handle.
  2275.  
  2276.                 pbuf            LPSTR    Pointer to the buffer containing
  2277.                                 the field's logical contents.
  2278.  
  2279.     Return Value    Nonzero if an error occurred.
  2280.  
  2281.     Comments    The resulting value in the buffer can be converted to a
  2282.                 double by calling the atof function.  This is useful in
  2283.                 validation functions.
  2284.  
  2285.     ________________________________________________________________________
  2286.  
  2287.     field_lock
  2288.  
  2289.     Syntax      LPFIELD    field_lock(hfield)
  2290.  
  2291.                 Locks a field's record in memory so it can be accessed.
  2292.  
  2293.                 Parameter       Type/Description
  2294.                 ---------       ----------------
  2295.                 hfield          HFIELD    The field's handle.
  2296.  
  2297.     Return Value    A far pointer to the field's record or NULL if an error
  2298.                     occurred.  See the description for the FIELD struct for
  2299.                     details.
  2300.  
  2301.     Comments    Once you have obtained a pointer to the field's record, you
  2302.                 are able to read or change any of the record's elements.
  2303.                 However, it is not recommended that you change the values of
  2304.                 any of the elements.
  2305.  
  2306.                 When you are done accessing the field's record, be sure to
  2307.                 call field_unlock.
  2308.  
  2309.  
  2310.                                       42   
  2311.  
  2312.                 Calling this function locks the field's record in the .DLL's
  2313.                 local heap.  In addition, the .DLL's entire data segment is
  2314.                 locked in the global heap.  This is required to ensure the
  2315.                 returned far pointer will remain valid until the call to
  2316.                 field_unlock.  For this reason, you should not keep the
  2317.                 field locked any longer than absolutely necessary.
  2318.  
  2319.     ________________________________________________________________________
  2320.  
  2321.     field_log_to_data
  2322.  
  2323.     Syntax      int    field_log_to_data(hfield, pbuf, pdata, data_type)
  2324.  
  2325.                 Converts a character string in logical field format to a
  2326.                 value in a specified data type.
  2327.  
  2328.                 Parameter       Type/Description
  2329.                 ---------       ----------------
  2330.                 hfield          HFIELD    The field's handle.
  2331.  
  2332.                 pbuf            LPSTR    Pointer to the buffer containing
  2333.                                 the string to convert.
  2334.  
  2335.                 pdata           LPVOID    Pointer to the data item to
  2336.                                 receive the converted value. This parameter
  2337.                                 can point to one of the following types:
  2338.                                 char (string), int, unsigned, long, unsigned
  2339.                                 long, or double.  The value you give for the
  2340.                                 data_type parameter must correspond to the
  2341.                                 data pointed to by pdata.
  2342.  
  2343.                 data_type       int    Specifies the data type pdata points
  2344.                                 to.  See the description of the field_define
  2345.                                 function for a list of possible values.
  2346.  
  2347.     Return Value    Nonzero if an error occurred.
  2348.  
  2349.     ________________________________________________________________________
  2350.  
  2351.     field_log_to_phys
  2352.  
  2353.     Syntax      int    field_log_to_phys(hfield, pbuf)
  2354.  
  2355.                 Converts a character string in logical field format to
  2356.                 physical field format.
  2357.  
  2358.                 Parameter       Type/Description
  2359.                 ---------       ----------------
  2360.                 hfield          HFIELD    The field's handle.
  2361.  
  2362.                 pbuf            LPSTR    Pointer to the buffer containing
  2363.                                 the string to convert.
  2364.  
  2365.  
  2366.                                       43   
  2367.  
  2368.     Return Value    Nonzero if an error occurred.
  2369.  
  2370.     ________________________________________________________________________
  2371.  
  2372.     field_phys_to_log
  2373.  
  2374.     Syntax      int    field_phys_to_log(hfield, pbuf)
  2375.  
  2376.                 Converts a character string in physical field format to
  2377.                 logical field format.
  2378.  
  2379.                 Parameter       Type/Description
  2380.                 ---------       ----------------
  2381.                 hfield          HFIELD    The field's handle.
  2382.  
  2383.                 pbuf            LPSTR    Pointer to the buffer containing
  2384.                                 the string to convert.
  2385.  
  2386.     Return Value    Nonzero if an error occurred.
  2387.  
  2388.     ________________________________________________________________________
  2389.  
  2390.     field_set_text
  2391.  
  2392.     Syntax      int    field_set_text(hfield, pbuf, physical)
  2393.  
  2394.                 Sets the contents of a field.
  2395.  
  2396.                 Parameter       Type/Description
  2397.                 ---------       ----------------
  2398.                 hfield          HFIELD    The field's handle.
  2399.  
  2400.                 pbuf            LPSTR    Pointer to the buffer containing
  2401.                                 the string to be used for the field's
  2402.                                 contents.
  2403.  
  2404.                 physical        BOOL    TRUE if the string pointed to by
  2405.                                 pbuf is in physical field format. FALSE if
  2406.                                 the string is in logical field format.
  2407.  
  2408.     Return Value    Nonzero if an error occurred.
  2409.  
  2410.     ________________________________________________________________________
  2411.  
  2412.     field_unlock
  2413.  
  2414.     Syntax      void    field_unlock(hfield)
  2415.  
  2416.                 Unlocks a field's record in memory.
  2417.  
  2418.                 Parameter       Type/Description
  2419.                 ---------       ----------------
  2420.  
  2421.  
  2422.                                       44   
  2423.                 hfield          HFIELD    The field's handle.
  2424.  
  2425.     Return Value    None.
  2426.  
  2427.     ________________________________________________________________________
  2428.  
  2429.     form_begin
  2430.  
  2431.     Syntax      HFORM  form_begin(hDlg)
  2432.  
  2433.                 Begins a form definition.
  2434.  
  2435.                 Parameter       Type/Description
  2436.                 ---------       ----------------
  2437.                 hDlg            HWND    The window handle of the dialog box.
  2438.  
  2439.     Return Value    The new form's handle or NULL if an error occurred. This
  2440.                     handle should be assigned to a static or global variable
  2441.                     for use in future function calls.
  2442.  
  2443.     Comments    This function must be called during the WM_INITDIALOG
  2444.                 message processing in the dialog procedure.  You should not
  2445.                 call any Windows functions which generate WM_COMMAND
  2446.                 messages before calling form_begin.  Be sure to call
  2447.                 form_end after all controls have been defined.
  2448.  
  2449.     ________________________________________________________________________
  2450.  
  2451.     form_end
  2452.  
  2453.     Syntax      int    form_end(hform)
  2454.  
  2455.                 Ends a form definition.
  2456.  
  2457.                 Parameter       Type/Description
  2458.                 ---------       ----------------
  2459.                 hform           HFORM    The form's handle.
  2460.  
  2461.     Return Value    Nonzero if an error occurred.
  2462.  
  2463.     Comments    This function must be called during the WM_INITDIALOG
  2464.                 message processing in the dialog procedure.  After calling
  2465.                 this function, no more controls can be defined.
  2466.  
  2467.     ________________________________________________________________________
  2468.  
  2469.     form_get_active
  2470.  
  2471.     Syntax      HFORM    form_get_active()
  2472.  
  2473.                 Gets the handle of the active form.
  2474.  
  2475.     Return Value    The handle of the active form or NULL if an error
  2476.  
  2477.  
  2478.                                       45   
  2479.                     occurred.
  2480.  
  2481.     ________________________________________________________________________
  2482.  
  2483.     form_get_from_hdlg
  2484.  
  2485.     Syntax      HFORM    form_get_from_hdlg(hDlg)
  2486.  
  2487.                 Gets the handle of a form associated with a given dialog box
  2488.                 window handle.
  2489.  
  2490.                 Parameter       Type/Description
  2491.                 ---------       ----------------
  2492.                 hDlg            HWND    The window handle of the dialog box.
  2493.  
  2494.     Return Value    The handle of the form associated with the input dialog
  2495.                     box window handle or NULL if an error occurred.
  2496.  
  2497.     ________________________________________________________________________
  2498.  
  2499.     form_has_changed
  2500.  
  2501.     Syntax      int    form_has_changed(hform)
  2502.  
  2503.                 Determines whether any of the defined fields or buttons of a
  2504.                 form have been changed by the user.
  2505.  
  2506.                 Parameter       Type/Description
  2507.                 ---------       ----------------
  2508.                 hform           HFORM    The form's handle.
  2509.  
  2510.     Return Value    TRUE if one or more defined fields or buttons have been
  2511.                     changed by the user, FALSE if no defined fields or
  2512.                     buttons have been changed, or -1 if an error occurred.
  2513.  
  2514.     ________________________________________________________________________
  2515.  
  2516.     form_in_error_cond
  2517.  
  2518.     Syntax      int    form_in_error_cond(hform)
  2519.  
  2520.                 Determines whether a form is in an error condition.
  2521.  
  2522.                 Parameter       Type/Description
  2523.                 ---------       ----------------
  2524.                 hform           HFORM    The form's handle.
  2525.  
  2526.     Return Value    TRUE if the form is in an error condition, FALSE if the
  2527.                     form is not in an error condition, or -1 if an error
  2528.                     occurred.
  2529.  
  2530.     Comments    When a validation error has occurred, the form is in an
  2531.                 error condition.  Even if a field's error handler is active,
  2532.  
  2533.  
  2534.                                       46   
  2535.                 messages are still sent to the dialog procedure.  It is
  2536.                 often desirable to check to see if the form is in an error
  2537.                 condition before processing these messages.  For example, if
  2538.                 the form is in an error condition, you would not want to any
  2539.                 IDOK processing to occur.  Calling this function first can
  2540.                 prevent this from happening.
  2541.  
  2542.     ________________________________________________________________________
  2543.  
  2544.     form_is_cancelled
  2545.  
  2546.     Syntax      int    form_is_cancelled(hform)
  2547.  
  2548.                 Determines whether a form has been cancelled.
  2549.  
  2550.                 Parameter       Type/Description
  2551.                 ---------       ----------------
  2552.                 hform           HFORM    The form's handle.
  2553.  
  2554.     Return Value    TRUE if the form has been cancelled, FALSE if the form
  2555.                     has not been cancelled, or -1 if an error occurred.
  2556.  
  2557.     Comments    The form is cancelled when the user presses the Escape key
  2558.                 or clicks on the "Cancel" button.  Even if the form has been
  2559.                 cancelled, messages are still sent to the dialog procedure.
  2560.                 It is often desirable to check to see if the form has been
  2561.                 cancelled before processing these messages.
  2562.  
  2563.     ________________________________________________________________________
  2564.  
  2565.     form_lock
  2566.  
  2567.     Syntax      LPFORM    form_lock(hform)
  2568.  
  2569.             Locks a form's record in memory so it can be accessed.
  2570.  
  2571.                 Parameter       Type/Description
  2572.                 ---------       ----------------
  2573.                 hform           HFORM    The form's handle.
  2574.  
  2575.     Return Value    A far pointer to the form's record or NULL if an error
  2576.                     occurred.  See the description for the FORM struct for
  2577.                     details.
  2578.  
  2579.     Comments    Once you have obtained a pointer to the form's record, you
  2580.                 are able to read or change any of the record's elements.
  2581.                 However, it is not recommended that you change the values of
  2582.                 any of the elements.
  2583.  
  2584.                 When you are done accessing the form's record, be sure to
  2585.                 call form_unlock.
  2586.  
  2587.                 Calling this function locks the form's record in the .DLL's
  2588.  
  2589.  
  2590.                                       47   
  2591.                 local heap.  In addition, the .DLL's entire data segment is
  2592.                 locked in the global heap.  This is required to ensure the
  2593.                 returned far pointer will remain valid until the call to
  2594.                 form_unlock.  For this reason, you should not keep the form
  2595.                 locked any longer than absolutely necessary.
  2596.  
  2597.     ________________________________________________________________________
  2598.  
  2599.     form_process
  2600.  
  2601.     Syntax      int    form_process(hform)
  2602.  
  2603.                 Processes all defined controls in a form.  Calling this
  2604.                 function copies the values contained in the defined fields
  2605.                 and buttons to the data items specified in the calls to
  2606.                 field_define and button_define.
  2607.  
  2608.                 Parameter       Type/Description
  2609.                 ---------       ----------------
  2610.                 hform           HFORM    The form's handle.
  2611.  
  2612.     Return Value    Nonzero if an error occurred.
  2613.  
  2614.     Comments    This function is normally called during IDOK processing of
  2615.                 the WM_COMMAND message in the dialog procedure.  The
  2616.                 dproc_enter_idok, form_in_error_cond, and form_validate
  2617.                 functions must be called first to ensure none of the fields'
  2618.                 values have been invalidated.  EndDialog cannot be called
  2619.                 until after calling this function.
  2620.  
  2621.     ________________________________________________________________________
  2622.  
  2623.     form_set_help
  2624.  
  2625.     Syntax      int    form_set_help(hform, help_file_name)
  2626.  
  2627.                 Sets the file name of the Windows Help file to be used for
  2628.                 context-sensitive help for individual controls in the dialog
  2629.                 box.
  2630.  
  2631.                 Parameter       Type/Description
  2632.                 ---------       ----------------
  2633.                 hform           HFORM    The form's handle.
  2634.  
  2635.                 help_file_name  LPSTR    Pointer to the character string
  2636.                                 containing the Windows Help file name.  The
  2637.                                 full drive:path specification can be
  2638.                                 included.
  2639.  
  2640.     Return Value    Nonzero if an error occurred.
  2641.  
  2642.     Comments    This function must be called if context-sensitive help is to
  2643.                 be applied to individual controls.
  2644.  
  2645.  
  2646.                                       48   
  2647.  
  2648.     ________________________________________________________________________
  2649.  
  2650.     form_terminate
  2651.  
  2652.     Syntax      int    form_terminate(hform)
  2653.  
  2654.                 Terminates the form.  All memory allocated by the form and
  2655.                 the defined controls within it will be freed.
  2656.  
  2657.                 Parameter       Type/Description
  2658.                 ---------       ----------------
  2659.                 hform           HFORM    The form's handle.
  2660.  
  2661.     Return Value    Nonzero if an error occurred.
  2662.  
  2663.     Comments    This function is normally called during IDOK and IDCANCEL
  2664.                 processing of the WM_COMMAND message in the dialog
  2665.                 procedure.  The call to EndDialog must be made before
  2666.                 calling this function.
  2667.  
  2668.                 All handles and pointers to the form and its defined
  2669.                 cotnrols will no longer be valid after calling this
  2670.                 function.
  2671.  
  2672.     ________________________________________________________________________
  2673.  
  2674.     form_unlock
  2675.  
  2676.     Syntax      void    form_unlock(hform)
  2677.  
  2678.                 Unlocks a form's record in memory.
  2679.  
  2680.                 Parameter       Type/Description
  2681.                 ---------       ----------------
  2682.                 hform           HFORM    The form's handle.
  2683.  
  2684.     Return Value    None.
  2685.  
  2686.     ________________________________________________________________________
  2687.  
  2688.     form_validate
  2689.  
  2690.     Syntax      HFIELD    form_validate(hform)
  2691.  
  2692.                 Validates all fields in a form.  If a field fails
  2693.                 validation, input focus will be set to the field in error.
  2694.  
  2695.                 Parameter       Type/Description
  2696.                 ---------       ----------------
  2697.                 hform           HFORM    The form's handle.
  2698.  
  2699.     Return Value    The handle of the field that failed validation or NULL
  2700.  
  2701.  
  2702.                                       49   
  2703.                     if all fields passed validation.  A value of -1 will be
  2704.                     returned in the event of an error.
  2705.  
  2706.     Comments    This function is normally called during IDOK processing of
  2707.                 the WM_COMMAND message in the dialog procedure.  The
  2708.                 dproc_enter_idok and form_in_error_cond functions must be
  2709.                 called before calling this function.
  2710.  
  2711.                 If a field fails validation, IDOK processing should be
  2712.                 discontinued.
  2713.  
  2714.     ________________________________________________________________________
  2715.  
  2716.     genctrl_define
  2717.  
  2718.     Syntax      HGENCTRL    genctrl_define(hform, ctrl_id, help_context)
  2719.  
  2720.                 Defines a generic control.
  2721.  
  2722.                 Parameter       Type/Description
  2723.                 ---------       ----------------
  2724.                 hform           HFORM    The form's handle.
  2725.  
  2726.                 ctrl_id         int    The dialog control ID of the control
  2727.                                 to define.
  2728.  
  2729.                 help_context    DWORD    The help context identifier of the
  2730.                                 Windows Help topic associated with the
  2731.                                 control.  If context-sensitive help is not
  2732.                                 being applied to the control, set
  2733.                                 help_context to 0.  If context-sensitive
  2734.                                 help is being applied to the control, the
  2735.                                 form_set_help function must be called prior
  2736.                                 to the F1 key being pressed.
  2737.  
  2738.     Return Value    The handle of the new generic control's record or NULL
  2739.                     if an error occurred.  An error can be caused by one of
  2740.                     the following conditions:
  2741.  
  2742.                         Control ID is invalid.
  2743.                         The form_end function has already been called.
  2744.                         Memory allocation error.
  2745.  
  2746.     ________________________________________________________________________
  2747.  
  2748.     statmsg_define
  2749.  
  2750.     Syntax      int    statmsg_define(hform, ctrl_id, which, onmsg, offmsg)
  2751.  
  2752.                 Defines a static text control to be used as a status message
  2753.                 for the Insert, CapsLock, or NumLock key.
  2754.  
  2755.                 Parameter       Type/Description
  2756.  
  2757.  
  2758.                                       50   
  2759.                 ---------       ----------------
  2760.                 hform           HFORM    The form's handle.
  2761.  
  2762.                 ctrl_id         int    The dialog control ID of the static
  2763.                                 text control to be used for the status
  2764.                                 message.
  2765.  
  2766.                 which           int    Identifier that specifies which
  2767.                                 status message is to be assigned to the
  2768.                                 control.  Can be one of the following
  2769.                                 values:
  2770.  
  2771.                                 Value           Meaning
  2772.                                 -----           -------
  2773.                                 SM_INSERT       Insert key status message.
  2774.  
  2775.                                 SM_CAPSLOCK     CapsLock key status message.
  2776.  
  2777.                                 SM_NUMLOCK      NumLock key status message.
  2778.  
  2779.                 onmsg           LPSTR    The message to set the static text
  2780.                                 control to when the key identified by which
  2781.                                 is toggled on.
  2782.  
  2783.                 offmsg          LPSTR    The message to set the static text
  2784.                                 control to when the key identified by which
  2785.                                 is toggled off.
  2786.  
  2787.     Return Value    Nonzero if an error occurred.
  2788.  
  2789.     Comments    The static text control used for the key status message will
  2790.                 be updated automatically when the user toggles the key.
  2791.                 However, if the key is toggled while the user is in a
  2792.                 control that has not been defined, the message will not be
  2793.                 updated until the user moves to a control that has been
  2794.                 defined.
  2795.  
  2796.     ________________________________________________________________________
  2797.  
  2798.     str_delete_char
  2799.  
  2800.     Syntax      int    str_delete_char(pstr, ch)
  2801.  
  2802.                 Deletes the first occurrence of a character from a string.
  2803.  
  2804.                 Parameter       Type/Description
  2805.                 ---------       ----------------
  2806.                 pstr            LPSTR    Pointer to the string to operate
  2807.                                 on.
  2808.  
  2809.                 ch              int    The character to delete.
  2810.  
  2811.     Return Value    Nonzero if the character was not found.
  2812.  
  2813.  
  2814.                                       51   
  2815.  
  2816.     ________________________________________________________________________
  2817.  
  2818.     str_insert_char
  2819.  
  2820.     Syntax      void    str_insert_char(pstr, ch, offs)
  2821.  
  2822.                 Inserts a character into a string.
  2823.  
  2824.                 Parameter       Type/Description
  2825.                 ---------       ----------------
  2826.                 pstr            LPSTR    Pointer to the string to operate
  2827.                                 on.
  2828.  
  2829.                 ch              int    The character to insert.
  2830.  
  2831.                 offs            int    The offset into the string where the
  2832.                                 character is to be inserted.
  2833.  
  2834.     Return Value    None.
  2835.  
  2836.     ________________________________________________________________________
  2837.  
  2838.     str_is_blank
  2839.  
  2840.     Syntax      BOOL    str_is_blank(pstr)
  2841.  
  2842.                 Determines whether a string is blank.
  2843.  
  2844.                 Parameter       Type/Description
  2845.                 ---------       ----------------
  2846.                 pstr            LPSTR    Pointer to the string to test.
  2847.  
  2848.     Return Value    TRUE if the string is blank; otherwise FALSE.
  2849.  
  2850.     ________________________________________________________________________
  2851.  
  2852.     str_is_value_zero
  2853.  
  2854.     Syntax      BOOL    str_is_value_zero(pstr)
  2855.  
  2856.                 Determines whether a string contains a numeric value of
  2857.                 zero.
  2858.  
  2859.                 Parameter       Type/Description
  2860.                 ---------       ----------------
  2861.                 pstr            LPSTR    Pointer to the string to test.
  2862.  
  2863.     Return Value    TRUE if the string contains a numeric value of zero;
  2864.                     otherwise FALSE.
  2865.  
  2866.     ________________________________________________________________________
  2867.  
  2868.  
  2869.  
  2870.                                       52   
  2871.     str_trim_spaces
  2872.  
  2873.     Syntax      void    str_trim_spaces(pstr)
  2874.  
  2875.                 Trims trailing spaces from a string.
  2876.  
  2877.                 Parameter       Type/Description
  2878.                 ---------       ----------------
  2879.                 pstr            LPSTR    Pointer to the string to operate
  2880.                                 on.
  2881.  
  2882.     Return Value    None.
  2883.  
  2884.  
  2885.  
  2886.  
  2887.  
  2888.  
  2889.  
  2890.  
  2891.  
  2892.  
  2893.  
  2894.  
  2895.  
  2896.  
  2897.  
  2898.  
  2899.  
  2900.  
  2901.  
  2902.  
  2903.  
  2904.  
  2905.  
  2906.  
  2907.  
  2908.  
  2909.  
  2910.  
  2911.  
  2912.  
  2913.  
  2914.  
  2915.  
  2916.  
  2917.  
  2918.  
  2919.  
  2920.  
  2921.  
  2922.  
  2923.  
  2924.  
  2925.  
  2926.                                       53   
  2927.  
  2928.  
  2929.  
  2930.  
  2931.  
  2932.  
  2933.  
  2934.  
  2935.  
  2936.  
  2937.  
  2938.  
  2939.  
  2940.  
  2941.  
  2942.  
  2943.  
  2944.  
  2945.  
  2946.  
  2947.  
  2948.  
  2949.  
  2950.  
  2951.  
  2952.  
  2953.                               Data Type Reference
  2954.  
  2955.  
  2956.  
  2957.  
  2958.  
  2959.  
  2960.  
  2961.  
  2962.  
  2963.  
  2964.  
  2965.  
  2966.  
  2967.  
  2968.  
  2969.  
  2970.  
  2971.  
  2972.  
  2973.  
  2974.  
  2975.  
  2976.  
  2977.  
  2978.  
  2979.  
  2980.  
  2981.  
  2982.                                       54   
  2983.  
  2984.     BUTTON
  2985.  
  2986.     Button Record
  2987.  
  2988.             The BUTTON structure contains information about a defined
  2989.             button.
  2990.  
  2991.             typedef struct {
  2992.                 HWND hWnd;
  2993.                 HBUTTON hbutton;
  2994.                 HBUTTON hnext_button;
  2995.                 int ctrl_id;
  2996.                 LPINT pdata;
  2997.                 int group_id;
  2998.                 int on_value;
  2999.                 int off_value;
  3000.                 DWORD help_context;
  3001.                 BOOL has_changed;
  3002.             } BUTTON;
  3003.  
  3004.             The BUTTON structure contains the following elements:
  3005.  
  3006.             Element         Description
  3007.             -------         -----------
  3008.             hWnd            Window handle of the button control.
  3009.  
  3010.             hbutton         Handle of the BUTTON data structure.
  3011.                             (Self-reference)
  3012.  
  3013.             hnext_button    Handle of the next BUTTON data structure in the
  3014.                             linked list of buttons.
  3015.  
  3016.             ctrl_id         Dialog control ID of the button control
  3017.                             associated with the button.
  3018.  
  3019.             pdata           Pointer to the integer variable being updated or
  3020.                             initialized by the button.
  3021.  
  3022.             group_id        Group ID of the button.  Other buttons with the
  3023.                             same group ID belong to the same group as this
  3024.                             button.
  3025.  
  3026.             on_value        The value that will be stored at the integer
  3027.                             variable pointed to by pdata if the button is
  3028.                             checked.
  3029.  
  3030.             off_value       The value that will be stored at the integer
  3031.                             variable pointed to by pdata if the button is
  3032.                             not checked.
  3033.  
  3034.             help_context    The help context identifier of the Windows Help
  3035.                             topic associated with the button. has_changed
  3036.  
  3037.  
  3038.                                       55   
  3039.                             Flag indicating whether the button has been
  3040.                             changed by the user.
  3041.  
  3042.     Comments    The values of these elements should not be directly changed.
  3043.  
  3044.     ________________________________________________________________________
  3045.  
  3046.     FIELD
  3047.  
  3048.     Field Record
  3049.  
  3050.             The FIELD structure contains information about a defined field.
  3051.  
  3052.             typedef struct {
  3053.                 HWND hwnd;
  3054.                 HWND hcombo;
  3055.                 HFIELD hfield;
  3056.                 HFIELD hnext_field;
  3057.                 int ctrl_id;
  3058.                 LPVOID pdata;
  3059.                 int data_type;
  3060.                 LPSTR picture_string;
  3061.                 DWORD features;
  3062.                 int (FAR PASCAL *pvalid_func) (LPSTR);
  3063.                 int error_value;
  3064.                 DWORD help_context;
  3065.                 BOOL has_changed;
  3066.                 int logical_size;
  3067.                 int physical_size;
  3068.                 int decimal_position;
  3069.             } FIELD;
  3070.  
  3071.             The FIELD structure contains the following elements:
  3072.  
  3073.             Element         Description
  3074.             -------         -----------
  3075.             hwnd            Window handle of the field's edit control.
  3076.  
  3077.             hcombo          Window handle of the combo box a field belongs
  3078.                             to.
  3079.  
  3080.             hfield          Handle of the FIELD data structure.
  3081.                             (Self-reference)
  3082.  
  3083.             hnext_field     Handle of the next FIELD data structure in the
  3084.                             linked list of fields.
  3085.  
  3086.             ctrl_id         Dialog control ID of the edit control associated
  3087.                             with the field.
  3088.  
  3089.             pdata           Pointer to the data item being updated or
  3090.                             initialized by the field.  This can point to a
  3091.                             character string, integer, unsigned integer,
  3092.  
  3093.  
  3094.                                       56   
  3095.                             long integer, unsigned long integer, or double
  3096.                             precision floating point data type.
  3097.  
  3098.             data_type       Specifies what pdata points to.  See the
  3099.                             description of the field_define function for a
  3100.                             list of possible values.
  3101.  
  3102.             picture_string  Pointer to the picture string associated with
  3103.                             the field.
  3104.  
  3105.             features        Contains one or more field features combined
  3106.                             with the bitwise OR operator.  See the
  3107.                             description of the field_define function for a
  3108.                             list of possible values.
  3109.  
  3110.             pvalid_func     Procedure-instance address of the field's
  3111.                             validation function.
  3112.  
  3113.             error_value     Value that gets passed to the dialog procedure
  3114.                             (in the wParam parameter of the WM_COMMAND
  3115.                             message) when the validation function returns an
  3116.                             error.
  3117.  
  3118.             help_context    The help context identifier of the Windows Help
  3119.                             topic associated with the field.
  3120.  
  3121.             has_changed     Flag indicating whether the field has been
  3122.                             edited by the user.
  3123.  
  3124.             logical_size    Logical size of the field.
  3125.  
  3126.             physical_size   Physical size of the field.
  3127.  
  3128.             decimal_position    Virtual logical position of the decimal
  3129.                                 point.
  3130.  
  3131.     Comments    The values of these elements should not be directly changed.
  3132.  
  3133.     ________________________________________________________________________
  3134.  
  3135.     FIELD_POS
  3136.  
  3137.     Field Position Information
  3138.  
  3139.             The FIELD_POS structure contains information about a position in
  3140.             a field.
  3141.  
  3142.             typedef struct {
  3143.                 long selection;
  3144.                 int physical_position;
  3145.                 int logical_position;
  3146.                 BOOL to_right_of_dec;
  3147.                 LPSTR ppicture_str_pos;
  3148.  
  3149.  
  3150.                                       57   
  3151.                 int val_char_occ;
  3152.                 char validation_char;
  3153.             } FIELD_POS;
  3154.  
  3155.             The FIELD_POS structure contains the following elements:
  3156.  
  3157.             Element             Description
  3158.             -------             -----------
  3159.             selection           The field's selection.  The low-order word
  3160.                                 will always be equal to the high-order word.
  3161.  
  3162.             physical_position   The field's physical position.  The
  3163.                                 low-order and high-order words of selection
  3164.                                 are equal to this value.
  3165.  
  3166.             logical_position    The field's logical position.
  3167.  
  3168.             to_right_of_dec     Flag indicating whether the position is on
  3169.                                 the right-hand side of the decimal.
  3170.  
  3171.             ppicture_str_pos    Pointer to the position in the picture
  3172.                                 string that is associated with the position.
  3173.  
  3174.             val_char_occ        Validation character occurrence.  When there
  3175.                                 is multiple occurrence validation characters
  3176.                                 (such as "A(25)") in a field, the values for
  3177.                                 ppicture_str_pos and validation_char will
  3178.                                 remain the same regardless of which
  3179.                                 occurrence the position is at.  The
  3180.                                 val_char_occ identifies which occurrence the
  3181.                                 position is associated with.
  3182.  
  3183.             validation_char     The validation character.  See Appendix A
  3184.                                 for a list of possible values.
  3185.  
  3186.     ________________________________________________________________________
  3187.  
  3188.     FORM
  3189.  
  3190.     Form Record
  3191.  
  3192.             The FORM structure contains information about a form.
  3193.  
  3194.             typedef struct {
  3195.                 HWND hdlg;
  3196.                 HFORM hform;
  3197.                 HFORM hnext_form;
  3198.                 HFIELD hhead_field;
  3199.                 HFIELD hcurr_field;
  3200.                 HBUTTON hhead_button;
  3201.                 HANDLE hproc_array;
  3202.                 int num_controls;
  3203.                 LPSTR help_file_name;
  3204.  
  3205.  
  3206.                                       58   
  3207.                 int insert_id;
  3208.                 LPSTR insert_onmsg;
  3209.                 LPSTR insert_offmsg;
  3210.                 int capslock_id;
  3211.                 LPSTR capslock_onmsg;
  3212.                 LPSTR capslock_offmsg;
  3213.                 int numlock_id;
  3214.                 LPSTR numlock_onmsg;
  3215.                 LPSTR numlock_offmsg;
  3216.                 BOOL pressed_cancel;
  3217.                 BOOL error_condition;
  3218.                 BOOL ignore_ok;
  3219.                 BOOL edit_key_pressed;
  3220.                 BOOL just_passed_dec;
  3221.                 BOOL help_invoked;
  3222.             } FORM;
  3223.  
  3224.             The FORM structure contains the following elements:
  3225.  
  3226.             Element             Description
  3227.             -------             -----------
  3228.             hdlg                The window handle of the dialog box
  3229.                                 associated with the form.
  3230.  
  3231.             hform               Handle of the FORM data structure.
  3232.                                 (Self-reference)
  3233.  
  3234.             hnext_form          Handle of the next FORM data structure in
  3235.                                 the linked list of forms.
  3236.  
  3237.             hhead_field         Handle of the head FIELD structure in the
  3238.                                 linked list of fields.
  3239.  
  3240.             hcurr_field         Handle of the FIELD structure of the current
  3241.                                 field.
  3242.  
  3243.             hhead_button        Handle of the head BUTTON structure in the
  3244.                                 linked list of buttons.
  3245.  
  3246.             hproc_array         Handle of the memory block which contains
  3247.                                 the window procedure array that holds the
  3248.                                 window procedure addresses for each defined
  3249.                                 control.
  3250.  
  3251.             num_controls        Number of defined controls in the form.
  3252.  
  3253.             help_file_name      Pointer to the character string containing
  3254.                                 the help file name.
  3255.  
  3256.             insert_id           Dialog control ID of the static text control
  3257.                                 used for the Insert key status message.
  3258.  
  3259.             insert_onmsg        Pointer to the character string containing
  3260.  
  3261.  
  3262.                                       59   
  3263.                                 the message indicating the Insert key is on.
  3264.  
  3265.             insert_offmsg       Pointer to the character string containing
  3266.                                 the message indicating the Insert key is
  3267.                                 off.
  3268.  
  3269.             capslock_id         Dialog control ID of the static text control
  3270.                                 used for the CapsLock key status message.
  3271.  
  3272.             capslock_onmsg      Pointer to the character string containing
  3273.                                 the message indicating the CapsLock key is
  3274.                                 on.
  3275.  
  3276.             capslock_offmsg     Pointer to the character string containing
  3277.                                 the message indicating the CapsLock key is
  3278.                                 off.
  3279.  
  3280.             numlock_id          Dialog control ID of the static text control
  3281.                                 used for the NumLock key status message.
  3282.  
  3283.             numlock_onmsg       Pointer to the character string containing
  3284.                                 the message indicating the NumLock key is
  3285.                                 on.
  3286.  
  3287.             numlock_offmsg      Pointer to the character string containing
  3288.                                 the message indicating the NumLock key is
  3289.                                 off.
  3290.  
  3291.             pressed_cancel      Flag indicating whether the user pressed or
  3292.                                 clicked on the "Cancel" button.
  3293.  
  3294.             error_condition     Flag indicating whether the form is in an
  3295.                                 error condition. The form is in an error
  3296.                                 condition when a field fails validation.
  3297.  
  3298.             ignore_ok           Flag indicating whether the "OK" button or
  3299.                                 Enter key should be ignored.  Used with
  3300.                                 field validation.
  3301.  
  3302.             edit_key_pressed    Flag indicating whether the last key pressed
  3303.                                 was an editing key or a character key.
  3304.  
  3305.             just_passed_dec     Flag indicating whether the last keystroke
  3306.                                 moved the cursor from the position to the
  3307.                                 left of the decimal to the position to the
  3308.                                 right of the decimal.
  3309.  
  3310.             help_invoked        Flag indicating whether the Windows Help
  3311.                                 application has been invoked from within any
  3312.                                 of the defined controls.
  3313.  
  3314.     Comments    The values of these elements should not be directly changed.
  3315.  
  3316.  
  3317.  
  3318.                                       60   
  3319.     ________________________________________________________________________
  3320.  
  3321.     HBUTTON
  3322.  
  3323.     Handle of a BUTTON Structure
  3324.  
  3325.             typedef HANDLE HBUTTON;
  3326.  
  3327.     ________________________________________________________________________
  3328.  
  3329.     HFIELD
  3330.  
  3331.     Handle of a FIELD Structure
  3332.  
  3333.             typedef HANDLE HFIELD;
  3334.  
  3335.     ________________________________________________________________________
  3336.  
  3337.     HFORM
  3338.  
  3339.     Handle of a FORM Structure
  3340.  
  3341.             typedef HANDLE HFORM;
  3342.  
  3343.     ________________________________________________________________________
  3344.  
  3345.     HGENCTRL
  3346.  
  3347.     Handle of a Generic Control Record
  3348.  
  3349.             typedef HBUTTON HGENCTRL;
  3350.  
  3351.     Comments    The BUTTON data structure is used for storage of information
  3352.                 about a generic control.
  3353.  
  3354.     ________________________________________________________________________
  3355.  
  3356.     LPBUTTON
  3357.  
  3358.     Far Pointer to a BUTTON Structure
  3359.  
  3360.             typedef BUTTON FAR * LPBUTTON;
  3361.  
  3362.     ________________________________________________________________________
  3363.  
  3364.     LPFIELD
  3365.  
  3366.     Far Pointer to a FIELD Structure
  3367.  
  3368.             typedef FIELD FAR * LPFIELD;
  3369.  
  3370.     ________________________________________________________________________
  3371.  
  3372.  
  3373.  
  3374.                                       61   
  3375.     LPFIELD_POS
  3376.  
  3377.     Far Pointer to a FIELD_POS Structure
  3378.  
  3379.             typedef FIELD_POS FAR * LPFIELD_POS;
  3380.  
  3381.     ________________________________________________________________________
  3382.  
  3383.     LPFORM
  3384.  
  3385.     Far Pointer to a FORM Structure
  3386.  
  3387.             typedef FORM FAR * LPFORM;
  3388.  
  3389.     ________________________________________________________________________
  3390.  
  3391.     PBUTTON
  3392.  
  3393.     Pointer to a BUTTON Structure
  3394.  
  3395.             typedef BUTTON * PBUTTON;
  3396.  
  3397.     ________________________________________________________________________
  3398.  
  3399.     PFIELD
  3400.  
  3401.     Pointer to a FIELD Structure
  3402.  
  3403.             typedef FIELD * PFIELD;
  3404.  
  3405.     ________________________________________________________________________
  3406.  
  3407.     PFIELD_POS
  3408.  
  3409.     Pointer to a FIELD_POS Structure
  3410.  
  3411.             typedef FIELD_POS * PFIELD_POS;
  3412.  
  3413.     ________________________________________________________________________
  3414.  
  3415.     PFORM
  3416.  
  3417.     Pointer to a FORM Structure
  3418.  
  3419.             typedef FORM * PFORM;
  3420.  
  3421.     ________________________________________________________________________
  3422.  
  3423.     PROC_ARRAY_INFO
  3424.  
  3425.     Dialog Control Window Procedure Array Information
  3426.  
  3427.             The PROC_ARRAY_INFO structure is used to hold information about
  3428.  
  3429.  
  3430.                                       62   
  3431.             a dialog control's window procedure.
  3432.  
  3433.             typedef struct {
  3434.                 HWND hWnd;
  3435.                 FARPROC lpProc;
  3436.             } PROC_ARRAY_INFO;
  3437.  
  3438.             The PROC_ARRAY_INFO structure contains the following elements:
  3439.  
  3440.             Element     Description
  3441.             -------     -----------
  3442.             hWnd        The window handle of the dialog control.
  3443.  
  3444.             lpProc      Pointer to the dialog control's window procedure.
  3445.  
  3446.     Comments    The window procedure array is not accessible.  This data
  3447.                 structure is listed solely because it appears in the library
  3448.                 header file.
  3449.  
  3450.  
  3451.  
  3452.  
  3453.  
  3454.  
  3455.  
  3456.  
  3457.  
  3458.  
  3459.  
  3460.  
  3461.  
  3462.  
  3463.  
  3464.  
  3465.  
  3466.  
  3467.  
  3468.  
  3469.  
  3470.  
  3471.  
  3472.  
  3473.  
  3474.  
  3475.  
  3476.  
  3477.  
  3478.  
  3479.  
  3480.  
  3481.  
  3482.  
  3483.  
  3484.  
  3485.  
  3486.                                       63   
  3487.  
  3488.     Appendix A:  Picture String Characters
  3489.  
  3490.  
  3491.     Character       Meaning
  3492.     ---------       -------
  3493.     9               Accept an integer numeric character (0 - 9).
  3494.  
  3495.     #               Accept a real numeric character (0 - 9, -, +, ., E, e).
  3496.  
  3497.     A               Accept an alphabetic character (A - Z, a - z).  Foreign
  3498.                     alphabetic characters are supported.
  3499.  
  3500.     X               Accept an alphanumeric character (A - Z, a - z, 0 - 9).
  3501.                     Foreign alphabetic characters are supported.
  3502.  
  3503.     Y               Accept a yes/no character (Y, y, N, n).
  3504.  
  3505.     D               Accept a date character (0 - 9, -, /).
  3506.  
  3507.     T               Accept a telephone number character (0 - 9, (, ), -, +).
  3508.  
  3509.     F               Accept a file name character (any character except \, :,
  3510.                     *, ?, ;, ,, =, +, <, >, |, /, [, ], ").
  3511.  
  3512.     P               Accept a pathspec character (any character except ;, ,,
  3513.                     =, +, <, >, |, /, [, ], ").
  3514.  
  3515.     ?               Accept any printable character.
  3516.  
  3517.     !               Accept any printable character.  If the character is a
  3518.                     lowercase letter, convert it to uppercase.  Foreign
  3519.                     alphabetic characters are supported.
  3520.  
  3521.     < ..... >       Accept only one of the characters listed between the
  3522.                     angle brackets. For example, "<0123>" will accept only
  3523.                     0, 1, 2, or 3.  Also you can specify a range using two
  3524.                     periods between the two range limiting characters.  For
  3525.                     example, "<0..3>" would be equivalent to "<0123>".  Or
  3526.                     you can get fancy, "<0..3>5<7..9>" would accept 0, 1, 2,
  3527.                     3, 5, 7, 8, or 9. Characters are converted to uppercase.
  3528.                     For example, "<A..Z>" will accept any uppercase or
  3529.                     lowercase letter.
  3530.  
  3531.     > ..... <       Accept any character except the ones listed between the
  3532.                     angle brackets.  Works similar to the "<.....>"
  3533.                     characters.
  3534.  
  3535.     ( ..... )       Specifies multiple occurrences of one of the above
  3536.                     validation characters.  For example, "A(5)" is
  3537.                     equivalent to "AAAAA". "<0123>(3)" is equivalent to
  3538.                     "<0123><0123><0123>".  The open parenthesis must
  3539.                     immediately follow the validation character.
  3540.  
  3541.  
  3542.                                       64   
  3543.  
  3544.     ' ..... '       Insert formatting characters into field.  All characters
  3545.                     between the single quotes are formatting characters.
  3546.  
  3547.     \" ..... \"     Double quotes have the meaning as single quotes.  Useful
  3548.                     for when you need to insert formatting characters that
  3549.                     include the single quote character.  Note in the C
  3550.                     programming language, the backslashes preceding the
  3551.                     double quote characters are required.
  3552.  
  3553.     .               Special formatting character which specifies where the
  3554.                     decimal point will be in a numeric field.  You can only
  3555.                     have one decimal point in a picture string.  The field
  3556.                     must have either the FDF_NUMERIC or FDF_CALCNUM feature
  3557.                     defined.
  3558.  
  3559.     ,               Special formatting character which specifies where
  3560.                     conditional commas will be located in a calculator-style
  3561.                     numeric field.  A comma will only be displayed if a
  3562.                     digit exists to the left of it.  The field must have the
  3563.                     FDF_CALCNUM feature defined.
  3564.  
  3565.     space           The space character can be used throughout the picture
  3566.                     string to improve readability.  Do not put spaces
  3567.                     between angle brackets or quotes unless you intend for
  3568.                     them to be there.
  3569.  
  3570.  
  3571.  
  3572.  
  3573.  
  3574.  
  3575.  
  3576.  
  3577.  
  3578.  
  3579.  
  3580.  
  3581.  
  3582.  
  3583.  
  3584.  
  3585.  
  3586.  
  3587.  
  3588.  
  3589.  
  3590.  
  3591.  
  3592.  
  3593.  
  3594.  
  3595.  
  3596.  
  3597.  
  3598.                                       65   
  3599.  
  3600.     Appendix B:  Field Editing Keys
  3601.  
  3602.  
  3603.                               CURSOR MOVEMENT
  3604.  
  3605.     Editing Key         Action
  3606.     -----------         ------
  3607.     LeftArrow           Moves the cursor to the previous position.
  3608.  
  3609.     RightArrow          Moves the cursor to the next position.
  3610.  
  3611.     Ctrl-LeftArrow      Moves the cursor to the beginning of the previous
  3612.                         word.
  3613.  
  3614.     Ctrl-RightArrow     Moves the cursor to the beginning of the next word.
  3615.  
  3616.     Home                Moves the cursor to the first position in the field.
  3617.  
  3618.     End                 Moves the cursor to the position following the last
  3619.                         character in the field.
  3620.  
  3621.     Ctrl-End            Move the cursor to the last position in the field.
  3622.  
  3623.  
  3624.                               TEXT DELETION
  3625.  
  3626.     Editing Key         Action
  3627.     -----------         ------
  3628.     Backspace           Deletes the character to the left of the cursor.
  3629.  
  3630.     Delete              Deletes the character at the cursor.
  3631.  
  3632.     Ctrl-Backspace      Deletes the word to the left of the cursor.
  3633.  
  3634.     Ctrl-Delete         Deletes the word at the cursor.
  3635.  
  3636.     Ctrl-Shift-Delete   Deletes all characters to the right of the cursor.
  3637.  
  3638.  
  3639.  
  3640.                                   CLIPBOARD
  3641.  
  3642.     Editing Key         Action
  3643.     -----------         ------
  3644.     Ctrl-Insert         Copies the contents of field to the clipboard.
  3645.  
  3646.     Shift-Insert        Pastes the contents of the clipboard into the field.
  3647.  
  3648.     Shift-Delete        Cuts the contents of the field to the clipboard.
  3649.  
  3650.  
  3651.                                   TOGGLES
  3652.  
  3653.  
  3654.                                       66   
  3655.  
  3656.     Editing Key         Action
  3657.     -----------         ------
  3658.     Insert              Toggles Insert mode.
  3659.  
  3660.     CapsLock            Toggles Caps Lock mode.
  3661.  
  3662.     NumLock             Toggles Num Lock mode.
  3663.  
  3664.  
  3665.                                 MISCELLANEOUS
  3666.  
  3667.     Editing Key         Action
  3668.     -----------         ------
  3669.     Enter               Terminates processing of the form.  Field changes
  3670.                         are saved.
  3671.  
  3672.     Esc                 Terminates processing of the form.  None of the
  3673.                         field changes will be saved.
  3674.  
  3675.     Tab                 Sets the input focus to the next dialog control with
  3676.                         the WS_TABSTOP style.
  3677.  
  3678.     Shift-Tab           Sets the input focus to the previous dialog control
  3679.                         with the WS_TABSTOP style.
  3680.  
  3681.     Alt-Backspace       Restores the field to its previous contents.
  3682.  
  3683.     F1                  Displays context-sensitive help for the field.
  3684.  
  3685.  
  3686.  
  3687.  
  3688.  
  3689.  
  3690.  
  3691.  
  3692.  
  3693.  
  3694.  
  3695.  
  3696.  
  3697.  
  3698.  
  3699.  
  3700.  
  3701.  
  3702.  
  3703.  
  3704.  
  3705.  
  3706.  
  3707.  
  3708.  
  3709.  
  3710.                                       67   
  3711.  
  3712.  
  3713.     Appendix C:  Glossary
  3714.  
  3715.  
  3716.     button
  3717.         A button is a dialog box button control with an on and off state
  3718.         defined by the button_define function.  The button control is
  3719.         usually a radio button or check box.
  3720.  
  3721.     button control
  3722.         A button control is a Windows dialog control that can be set either
  3723.         on or off.  A button control is actually a window of class "button"
  3724.         and is a child of the dialog box window.
  3725.  
  3726.     cursor
  3727.         The cursor is the blinking vertical bar that identifies the user's
  3728.         position in a field. Throughout the Windows SDK documentation, the
  3729.         term "cursor" refers to the mouse pointer and the term "caret"
  3730.         refers to the cursor.
  3731.  
  3732.     edit control
  3733.         An edit control is a Windows dialog control that is used for the
  3734.         input of text information by the user.  An edit control is actually
  3735.         a window of class "edit" and is a child of the dialog box window.
  3736.  
  3737.     edit field
  3738.         Another name for an edit control.
  3739.  
  3740.     field
  3741.         A field is a dialog box edit control that has been defined by the
  3742.         field_define function.
  3743.  
  3744.     form
  3745.         A form is a dialog box with one or more WEDL-defined controls within
  3746.         it.
  3747.  
  3748.     formatting characters
  3749.         Formatting characters are the characters embedded in a field to
  3750.         assist the user in entering the correct data.  The positions of the
  3751.         formatting characters in a field are defined in the picture string.
  3752.         The user is not able to move the cursor to, or edit, the formatting
  3753.         characters. The '/' characters in a date field, and the '(', ')',
  3754.         and '-' characters in a phone number field are good examples of
  3755.         formatting characters.
  3756.  
  3757.     generic control
  3758.         A generic control can be any control in a dialog box defined by the
  3759.         genctrl_define function.
  3760.  
  3761.     logical field contents
  3762.         The logical field contents are the contents of a field without the
  3763.         embedded formatting characters.  To get the logical contents of a
  3764.  
  3765.  
  3766.                                       68   
  3767.         field, call the field_get_text function.
  3768.  
  3769.     logical field format
  3770.         A character string is in logical field format if it contains no
  3771.         embedded formatting characters and it can be used to set the
  3772.         contents of a field.  You can set the contents of a field using a
  3773.         character string in logical field format by calling the
  3774.         field_set_text function.
  3775.  
  3776.     mouse pointer
  3777.         The mouse pointer is the icon on the screen that identifies where
  3778.         the mouse currently is.  This icon is very often a white arrow, but
  3779.         can have just about any shape. Throughout the Windows SDK, the term
  3780.         "cursor" refers to the mouse pointer.
  3781.  
  3782.     physical field contents
  3783.         The physical field contents are the contents of a field including
  3784.         the embedded formatting characters.  If you were to call
  3785.         GetDlgItemText on the field, you would get its physical contents,
  3786.         but it is preferable to use the field_get_text function.
  3787.  
  3788.     physical field format
  3789.         A character string is in physical field format if it contains any
  3790.         embedded formatting characters and it can be used to set the
  3791.         contents of a field.  You can set the contents of a field using a
  3792.         character string in physical field format by calling the
  3793.         field_set_text function.
  3794.  
  3795.     picture string
  3796.         The picture string is a character string assigned to a field by the
  3797.         field_define function.  It is used to define the number of
  3798.         characters in a field, the allowable characters for each position in
  3799.         the field (validation characters), and the placement of formatting
  3800.         characters.  See Appendix A for a list of characters that can exist
  3801.         in a picture string.
  3802.  
  3803.     validation character
  3804.         A validation character is a character in a picture string which is
  3805.         used to define the allowable characters that can be input for the
  3806.         corresponding position in its field.  See Appendix A for a list of
  3807.         validation characters.
  3808.  
  3809.     validation function
  3810.         A validation function is a function written by the programmer to
  3811.         validate the information in a field.  A validation function is
  3812.         assigned to a field by the field_define function.
  3813.  
  3814.  
  3815.  
  3816.  
  3817.  
  3818.  
  3819.  
  3820.  
  3821.  
  3822.                                       69   
  3823.  
  3824.